import { createRouter, RouterProvider, RouterView, RouterLink } from '@pyreon/router'
import { mount } from '@pyreon/runtime-dom'

const router = createRouter({
  routes: [
    { path: '/', component: Home },
    { path: '/about', component: About },
    { path: '/user/:id', component: UserPage, name: 'user' },
    { path: '(.*)', component: NotFound },
  ],
})

function App() {
  return (
    <RouterProvider router={router}>
      <nav>
        <RouterLink to="/">Home</RouterLink>
        <RouterLink to="/about">About</RouterLink>
      </nav>
      <RouterView />
    </RouterProvider>
  )
}

mount(<App />, document.getElementById('app')!)

const router = createRouter({
  routes: [
    { path: '/', component: Home },
    { path: '/about', component: About },
  ],
  mode: 'history', // "hash" (default) or "history"
  scrollBehavior: 'restore', // "top" | "restore" | "none" | ScrollBehaviorFn
})

// Shorthand -- just pass the routes array:
const router = createRouter([
  { path: '/', component: Home },
  { path: '/about', component: About },
])

interface RouterOptions {
  routes: RouteRecord[]
  mode?: 'hash' | 'history'
  base?: string
  dataEndpoint?: string
  scrollBehavior?: ScrollBehaviorFn | 'top' | 'restore' | 'none'
  trailingSlash?: 'strip' | 'add' | 'ignore'
  url?: string
  onError?: (err: unknown, route: ResolvedRoute) => undefined | false
  maxCacheSize?: number
}

// Hash mode (default): URLs like /#/about
const router = createRouter({ routes, mode: 'hash' })

// History mode: clean URLs like /about (requires server-side fallback)
const router = createRouter({ routes, mode: 'history' })

const router = createRouter({
  routes,
  mode: 'history',
  base: '/app',
})

// router.push("/about") navigates to /app/about
// URL /app/user/42 matches route /user/:id with params.id = "42"

// Strip trailing slashes (default) — /about/ becomes /about
createRouter({ routes, trailingSlash: 'strip' })

// Always add trailing slash — /about becomes /about/
createRouter({ routes, trailingSlash: 'add' })

// No normalization — match paths exactly as-is
createRouter({ routes, trailingSlash: 'ignore' })

const router = createRouter({
  routes,
  onError: (err, route) => {
    console.error(`Loader failed for ${route.path}:`, err)
    // Return false to cancel the navigation
    // Return undefined to continue with undefined loader data
    return false
  },
})

interface RouteRecord<TPath extends string = string> {
  path: TPath
  component: RouteComponent
  name?: string
  meta?: RouteMeta
  redirect?: string | ((to: ResolvedRoute) => string)
  beforeEnter?: NavigationGuard | NavigationGuard[]
  beforeLeave?: NavigationGuard | NavigationGuard[]
  alias?: string | string[]
  children?: RouteRecord[]
  loader?: RouteLoaderFn
  serverLoader?: RouteLoaderFn
  hasServerLoader?: boolean
  staleWhileRevalidate?: boolean
  loaderKey?: (ctx: Pick<LoaderContext, 'params' | 'query'>) => string
  gcTime?: number
  errorComponent?: ComponentFn
  notFoundComponent?: ComponentFn
  pendingComponent?: ComponentFn
  pendingMs?: number
  pendingMinMs?: number
  validateSearch?: (raw: Record<string, string>) => Record<string, unknown>
  middleware?: RouteMiddleware | RouteMiddleware[]
}

{ path: "/about", component: About }
{ path: "/contact", component: Contact }

{ path: "/user/:id", component: UserPage }
// /user/42 => params.id = "42"

{ path: "/user/:id/posts/:postId", component: PostPage }
// /user/42/posts/7 => params.id = "42", params.postId = "7"

{ path: "/files/:path*", component: FileBrowser }
// /files/docs/readme.md => params.path = "docs/readme.md"
// /files/images/logo.png => params.path = "images/logo.png"

{ path: "/user/:id?", component: UserPage }
// /user => params.id = undefined
// /user/42 => params.id = "42"

{ path: "/page/:page?/settings/:setting?", component: SettingsPage }
// /page/settings => params.page = undefined, params.setting = undefined
// /page/1/settings/theme => params.page = "1", params.setting = "theme"

type Params = ExtractParams<'/user/:id?'>
// { id?: string | undefined }

buildPath('/user/:id?', {}) // "/user"
buildPath('/user/:id?', { id: '42' }) // "/user/42"

{ path: "(.*)", component: NotFound }
// or equivalently:
{ path: "*", component: NotFound }

const routes = [
  { path: '/', component: Home },
  { path: '/user/me', component: MyProfile }, // specific
  { path: '/user/:id', component: UserProfile }, // dynamic
  { path: '/user/:id/posts', component: UserPosts },
  { path: '(.*)', component: NotFound }, // catch-all last
]

import { useRoute } from '@pyreon/router'

// Inside a route with path "/user/:id/posts/:postId":
const route = useRoute<'/user/:id/posts/:postId'>()

route().params.id // string (typed!)
route().params.postId // string (typed!)
// route().params.foo  // TypeScript error -- "foo" does not exist

import type { ExtractParams } from '@pyreon/router'

type UserParams = ExtractParams<'/user/:id'>
// { id: string }

type PostParams = ExtractParams<'/user/:id/posts/:postId'>
// { id: string; postId: string }

type FileParams = ExtractParams<'/files/:path*'>
// { path: string }

type HomeParams = ExtractParams<'/'>
// Record<never, never> (empty object)

const routes = [
  {
    path: '/admin',
    component: AdminLayout,
    meta: { requiresAuth: true },
    children: [
      { path: 'users', component: AdminUsers }, // matches /admin/users
      { path: 'settings', component: AdminSettings }, // matches /admin/settings
      { path: 'users/:id', component: AdminUserDetail }, // matches /admin/users/42
    ],
  },
]

function AdminLayout() {
  return (
    <div class="admin">
      <Sidebar />
      <main>
        <RouterView /> {/* renders AdminUsers, AdminSettings, or AdminUserDetail */}
      </main>
    </div>
  )
}

const routes = [
  {
    path: '/dashboard',
    component: DashboardLayout,
    children: [
      {
        path: 'analytics',
        component: AnalyticsLayout,
        children: [
          { path: 'overview', component: AnalyticsOverview }, // /dashboard/analytics/overview
          { path: 'reports', component: AnalyticsReports }, // /dashboard/analytics/reports
        ],
      },
      { path: 'settings', component: DashboardSettings }, // /dashboard/settings
    ],
  },
]

function DashboardLayout() {
  return (
    <div class="dashboard">
      <DashboardNav />
      <RouterView /> {/* level 1: AnalyticsLayout or DashboardSettings */}
    </div>
  )
}

function AnalyticsLayout() {
  return (
    <div class="analytics">
      <AnalyticsTabs />
      <RouterView /> {/* level 2: AnalyticsOverview or AnalyticsReports */}
    </div>
  )
}

interface RouteMeta {
  title?: string // Sets document.title on navigation
  description?: string // Page description (for meta tags)
  requiresAuth?: boolean // Guards can check this
  scrollBehavior?: 'top' | 'restore' | 'none'
}

const routes = [
  {
    path: '/admin',
    component: AdminLayout,
    meta: { requiresAuth: true, title: 'Admin' },
    children: [
      { path: 'users', component: AdminUsers, meta: { title: 'Admin - Users' } },
      { path: 'settings', component: AdminSettings, meta: { title: 'Admin - Settings' } },
    ],
  },
]

// Navigating to /admin/users:
// route.meta = { requiresAuth: true, title: "Admin - Users" }
// (title from child overrides parent, requiresAuth is inherited)

// globals.d.ts
declare module '@pyreon/router' {
  interface RouteMeta {
    requiresRole?: 'admin' | 'user' | 'guest'
    breadcrumb?: string
    transition?: 'fade' | 'slide'
    cacheable?: boolean
  }
}

const routes = [
  {
    path: '/admin',
    component: AdminLayout,
    meta: {
      requiresAuth: true,
      requiresRole: 'admin',
      breadcrumb: 'Admin',
    },
    children: [
      {
        path: 'users',
        component: AdminUsers,
        meta: { breadcrumb: 'Users', transition: 'slide' },
      },
    ],
  },
]

// Static redirect
{ path: "/old-page", redirect: "/new-page" }

// Dynamic redirect with access to the resolved route
{ path: "/legacy/:id", redirect: (to) => `/v2/${to.params.id}` }

const routes = [
  // Redirect /home to /
  { path: '/home', redirect: '/' },

  // Redirect with param forwarding
  { path: '/profile/:id', redirect: (to) => `/user/${to.params.id}` },

  // Redirect preserving query params
  { path: '/search-old', redirect: (to) => `/search?q=${to.query.q ?? ''}` },

  // Actual routes
  { path: '/', component: Home },
  { path: '/user/:id', component: UserPage },
  { path: '/search', component: SearchPage },
]

const routes = [
  {
    path: '/user/:id',
    component: UserProfile,
    alias: '/profile/:id', // single alias
  },
  {
    path: '/settings',
    component: Settings,
    alias: ['/preferences', '/config'], // multiple aliases
  },
]

const routes = [
  {
    path: '/feed',
    component: Feed,
    loader: async ({ signal }) => {
      const res = await fetch('/api/feed', { signal })
      return res.json()
    },
    staleWhileRevalidate: true,
  },
]

const routes = [
  {
    path: '/user/:id',
    component: UserProfile,
    loader: async ({ params, signal }) => {
      const res = await fetch(`/api/users/${params.id}`, { signal })
      return res.json()
    },
    // Cache identity — same key = served from cache, loader skipped
    loaderKey: ({ params }) => `user-${params.id}`,
    // Keep cached data 10 minutes before garbage collection (default: 5 min)
    gcTime: 10 * 60 * 1000,
  },
]

const router = useRouter()

// Invalidate ALL cached loader data
router.invalidateLoader()

// Invalidate by exact cache key (as returned by loaderKey)
router.invalidateLoader('user-42')

// Invalidate entries where a predicate matches the key
router.invalidateLoader((key) => key.startsWith('user-'))

const routes = [
  {
    path: '/dashboard',
    component: Dashboard,
    loader: loadDashboard,
    pendingComponent: DashboardSkeleton,
    pendingMs: 150, // wait 150ms before showing the skeleton (default: 0)
    pendingMinMs: 400, // once shown, keep it for at least 400ms (default: 200)
  },
]

const routes = [
  {
    path: '/search',
    component: SearchPage,
    // Plain function
    validateSearch: (raw) => ({
      page: Number(raw.page) || 1,
      q: raw.q ?? '',
    }),
  },
  {
    path: '/products',
    component: Products,
    // With Zod
    validateSearch: z.object({
      page: z.coerce.number().default(1),
      sort: z.enum(['name', 'price']).default('name'),
    }).parse,
  },
]

interface RouterProviderProps {
  router: Router
  children?: VNode | VNodeChild | null
}

<RouterProvider router={router}>
  <App />
</RouterProvider>

interface RouterViewProps {
  router?: Router // optional -- uses context by default
}

function App() {
  return (
    <RouterProvider router={router}>
      <RouterView />
    </RouterProvider>
  )
}

// In a nested layout:
function AdminLayout() {
  return (
    <div>
      <Sidebar />
      <RouterView /> {/* renders the matched child route */}
    </div>
  )
}

interface RouterLinkProps {
  to: string
  replace?: boolean
  activeClass?: string
  exactActiveClass?: string
  exact?: boolean
  prefetch?: 'intent' | 'hover' | 'viewport' | 'none'
  children?: VNodeChild | null
}

<RouterLink to="/about">About</RouterLink>

<RouterLink
  to="/users"
  activeClass="nav-active"
  exactActiveClass="nav-exact"
  exact
  prefetch="viewport"
  replace
>
  Users
</RouterLink>

// Current path: /admin/users

<RouterLink to="/admin">Admin</RouterLink>
// class="router-link-active" (prefix match)

<RouterLink to="/admin/users">Users</RouterLink>
// class="router-link-active router-link-exact-active" (exact match)

<RouterLink to="/">Home</RouterLink>
// No active class (/ is not applied as prefix by default)

// Default — no prefetch prop needed. Hover OR keyboard-focus this link
// and its loader data is already resolving before the click lands.
<RouterLink to="/about">About</RouterLink>

// Explicit intent (same as the default — shown for clarity)
<nav>
  <RouterLink to="/" prefetch="intent">Home</RouterLink>
  <RouterLink to="/dashboard" prefetch="intent">Dashboard</RouterLink>
</nav>

// Content feed — prefetch as links scroll near the viewport. The
// observer uses a 200px rootMargin so the fetch starts BEFORE the link
// is fully on screen, and runs in a requestIdleCallback slice so it
// never competes with the scroll the user is performing.
<ul>
  {posts.map(post => (
    <li>
      <RouterLink to={`/post/${post.id}`} prefetch="viewport">
        {post.title}
      </RouterLink>
    </li>
  ))}
</ul>

// Opt out for a link the user rarely clicks
<RouterLink to="/terms" prefetch="none">Terms of Service</RouterLink>

function useRouter(): Router

import { useRouter } from '@pyreon/router'

function MyComponent() {
  const router = useRouter()

  const goHome = () => router.push('/')
  const goBack = () => router.back()
  const isLoading = () => router.loading()

  return (
    <div>
      <button onClick={goHome}>Home</button>
      <button onClick={goBack}>Back</button>
      {isLoading() && <span>Loading...</span>}
    </div>
  )
}

function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath>>

import { useRoute } from '@pyreon/router'

function Breadcrumb() {
  const route = useRoute()

  return (
    <nav>
      <span>{route().path}</span>
      {Object.entries(route().query).map(([k, v]) => (
        <span>
          {k}={v}
        </span>
      ))}
    </nav>
  )
}

function UserProfile() {
  const route = useRoute<'/user/:id'>()

  return <p>User ID: {route().params.id}</p>
  // route().params.id is typed as string
}

interface ResolvedRoute<
  P extends Record<string, string> = Record<string, string>,
  Q extends Record<string, string> = Record<string, string>,
> {
  path: string // The matched path (without query or hash)
  params: P // Extracted route params
  query: Q // Parsed query string
  hash: string // Hash fragment (without #)
  matched: RouteRecord[] // All matched records from root to leaf
  meta: RouteMeta // Merged metadata from all matched records
}

function useSearchParams<T extends Record<string, string>>(
  defaults?: T,
): [get: () => T, set: (updates: Partial<T>) => Promise<void>]

import { useSearchParams } from '@pyreon/router'

function SearchPage() {
  const [query, setQuery] = useSearchParams({ q: '', page: '1' })

  return (
    <div>
      <input value={query().q} onInput={(e) => setQuery({ q: e.currentTarget.value })} />
      <p>Page: {query().page}</p>
      <button onClick={() => setQuery({ page: String(Number(query().page) + 1) })}>
        Next Page
      </button>
    </div>
  )
}

function useValidatedSearch<T>(): () => T

import { useValidatedSearch } from '@pyreon/router'

// Route: { path: '/search', validateSearch: (raw) => ({ page: Number(raw.page) || 1, q: raw.q ?? '' }) }
function SearchPage() {
  const search = useValidatedSearch<{ page: number; q: string }>()

  return (
    <div>
      <p>Query: {search().q}</p>
      <p>Page: {search().page}</p>
    </div>
  )
}

function useIsActive(path: string, exact?: boolean): () => boolean

import { useIsActive } from '@pyreon/router'

function NavItem(props: { to: string; label: string }) {
  const isActive = useIsActive(props.to)

  return (
    <a href={props.to} class={() => (isActive() ? 'nav-item active' : 'nav-item')}>
      {props.label}
    </a>
  )
}

function useBlocker(fn: BlockerFn): { remove(): void }

type BlockerFn = (to: ResolvedRoute, from: ResolvedRoute) => boolean | Promise<boolean>

import { useBlocker } from '@pyreon/router'

function Editor() {
  const dirty = signal(false)

  useBlocker((to, from) => {
    if (!dirty()) return false
    return !window.confirm('You have unsaved changes. Leave anyway?')
  })

  return <textarea onInput={() => dirty.set(true)} />
}

function onBeforeRouteLeave(guard: NavigationGuard): () => void

import { onBeforeRouteLeave } from '@pyreon/router'

function EditorPage() {
  onBeforeRouteLeave((to, from) => {
    if (hasUnsavedChanges()) {
      return false // cancel navigation
    }
  })

  return <div>...</div>
}

function onBeforeRouteUpdate(guard: NavigationGuard): () => void

import { onBeforeRouteUpdate } from '@pyreon/router'

function UserProfile() {
  onBeforeRouteUpdate(async (to, from) => {
    // Confirm before switching to a different user
    if (to.params.id !== from.params.id) {
      const ok = window.confirm(`Switch to user ${to.params.id}?`)
      if (!ok) return false
    }
  })

  return <div>...</div>
}

const router = useRouter()

// Navigate by path
await router.push('/user/42')

// Navigate by name with params
await router.push({ name: 'user', params: { id: '42' } })

// Navigate by name with query
await router.push({ name: 'search', query: { q: 'pyreon' } })

// Replace current history entry (no new entry in browser history)
await router.replace('/new-path')

// Replace with named route
await router.replace({ name: 'user', params: { id: '42' } })

// Go back / forward / arbitrary delta
router.back()
router.forward()
router.go(-2) // go back 2 steps
router.go(1) // same as forward()

const routes = [
  { path: '/user/:id', component: UserPage, name: 'user' },
  { path: '/user/:id/posts/:postId', component: PostPage, name: 'post' },
]

// Navigate by name
router.push({ name: 'user', params: { id: '42' } })
// => /user/42

router.push({ name: 'post', params: { id: '42', postId: '7' } })
// => /user/42/posts/7

// With query params
router.push({ name: 'user', params: { id: '42' }, query: { tab: 'posts' } })
// => /user/42?tab=posts

async function handleLogin() {
  await authenticate()
  await router.push('/dashboard')
  // Navigation is complete, dashboard is rendered
}

router.push('javascript:alert(1)') // blocked, navigates to /
router.push('data:text/html,...') // blocked, navigates to /

// Before each navigation
const removeGuard = router.beforeEach(async (to, from) => {
  // Check authentication
  if (to.meta.requiresAuth && !isAuthenticated()) {
    return '/login' // redirect to login
  }
  // return undefined or true to allow
  // return false to cancel
})

// Remove the guard later
removeGuard()

// After each navigation (cannot cancel or redirect)
const removeHook = router.afterEach((to, from) => {
  analytics.trackPageView(to.path)
})

removeHook()

const routes = [
  {
    path: '/admin',
    component: AdminLayout,
    beforeEnter: (to, from) => {
      if (!isAdmin()) return '/unauthorized'
    },
    beforeLeave: (to, from) => {
      if (hasUnsavedChanges()) return false // cancel navigation
    },
  },
]

{
  path: "/admin/settings",
  component: AdminSettings,
  beforeEnter: [
    // Guard 1: check auth
    (to, from) => {
      if (!isAuthenticated()) return "/login"
    },
    // Guard 2: check role
    (to, from) => {
      if (!isAdmin()) return "/unauthorized"
    },
  ],
}

router.beforeEach(async (to, from) => {
  // Async check
  const allowed = await checkPermission(to.path)
  if (!allowed) return '/forbidden'
})

type NavigationGuardResult = boolean | string | undefined

type NavigationGuard = (
  to: ResolvedRoute,
  from: ResolvedRoute,
) => NavigationGuardResult | Promise<NavigationGuardResult>

type AfterEachHook = (to: ResolvedRoute, from: ResolvedRoute) => void

const routes = [
  {
    path: "/users",
    component: Users,
    loader: async ({ params, query, signal }) => {
      const res = await fetch("/api/users", { signal })
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return res.json()
    },
    errorComponent: UsersError, // shown if loader fails
  },
]

function Users() {
  const users = useLoaderData<User[]>()
  return (
    <ul>
      {users.map(u => <li>{u.name}</li>)}
    </ul>
  )
}

function UsersError() {
  return <p>Failed to load users. Please try again.</p>
}

interface LoaderContext {
  params: Record<string, string> // Route params
  query: Record<string, string> // Query string params
  signal: AbortSignal // Aborted when a newer navigation starts
  request?: Request // The incoming HTTP Request — server-side runs only, undefined for CSR loaders
}

loader: ({ request }) => {
  const cookie = request?.headers.get('cookie') ?? ''
  const sid = cookie.match(/sid=([^;]+)/)?.[1]
  if (!sid) throw redirect('/login')
  return loadSession(sid)
}

const routes = [
  {
    path: "/user/:id",
    component: UserProfile,
    loader: async ({ params, signal }) => {
      const res = await fetch(`/api/users/${params.id}`, { signal })
      return res.json()
    },
  },
  {
    path: "/search",
    component: SearchResults,
    loader: async ({ query, signal }) => {
      const res = await fetch(`/api/search?q=${query.q ?? ""}`, { signal })
      return res.json()
    },
  },
]

function UserProfile() {
  const user = useLoaderData<User>()
  return <h1>{user.name}</h1>
}

function SearchResults() {
  const results = useLoaderData<SearchResult[]>()
  return (
    <ul>
      {results.map(r => <li>{r.title}</li>)}
    </ul>
  )
}

const routes = [
  {
    path: '/org/:orgId',
    component: OrgLayout,
    loader: async ({ params, signal }) => {
      const res = await fetch(`/api/orgs/${params.orgId}`, { signal })
      return res.json()
    },
    children: [
      {
        path: 'members',
        component: OrgMembers,
        loader: async ({ params, signal }) => {
          const res = await fetch(`/api/orgs/${params.orgId}/members`, { signal })
          return res.json()
        },
      },
    ],
  },
]

function OrgLayout() {
  const org = useLoaderData<Organization>()
  return (
    <div>
      <h1>{org.name}</h1>
      <RouterView />
    </div>
  )
}

function OrgMembers() {
  const members = useLoaderData<Member[]>()
  return (
    <ul>
      {members.map((m) => (
        <li>{m.name}</li>
      ))}
    </ul>
  )
}

import { createRouter, prefetchLoaderData, serializeLoaderData } from '@pyreon/router'
import { renderToString } from '@pyreon/runtime-server'

// In your SSR handler:
const router = createRouter({ routes, url: req.url })

// Run all loaders for the matched route
await prefetchLoaderData(router, req.url)

// Render the app
const html = await renderToString(<App />)

// Serialize loader data for client hydration
const loaderData = JSON.stringify(serializeLoaderData(router))

// Include in HTML response:
const page = `
<!DOCTYPE html>
<html>
  <body>
    <div id="app">${html}</div>
    <script>window.__PYREON_LOADER_DATA__=${loaderData}</script>
    <script src="/client.js"></script>
  </body>
</html>
`

import { createRouter, hydrateLoaderData } from '@pyreon/router'
import { mount } from '@pyreon/runtime-dom'

const router = createRouter({ routes })

// Hydrate loader data so initial render uses server-fetched data
hydrateLoaderData(router, window.__PYREON_LOADER_DATA__ ?? {})

mount(<App />, document.getElementById('app')!)

import { redirect, type LoaderContext } from '@pyreon/router'

export const loader = async ({ request, params }: LoaderContext) => {
  const session = await getSession(request)
  if (!session) {
    throw redirect('/login?next=' + encodeURIComponent(params.path), 307)
  }
  return loadUser(session.userId)
}

import { isRedirectError, getRedirectInfo } from '@pyreon/router'

<ErrorBoundary
  fallback={(err) => {
    if (isRedirectError(err)) throw err  // re-throw, let the router handle it
    return <div>Error: {err.message}</div>
  }}
>
  <App />
</ErrorBoundary>

import { notFound, NotFoundBoundary, isNotFoundError } from '@pyreon/router'

const routes = [
  {
    path: '/user/:id',
    component: UserProfile,
    loader: async ({ params, signal }) => {
      const res = await fetch(`/api/users/${params.id}`, { signal })
      if (res.status === 404) throw notFound()
      return res.json()
    },
  },
]

function App() {
  return (
    <RouterProvider router={router}>
      <NotFoundBoundary fallback={() => <h1>404 — Not Found</h1>}>
        <RouterView />
      </NotFoundBoundary>
    </RouterProvider>
  )
}

<ErrorBoundary
  fallback={(err) => {
    if (isNotFoundError(err)) return <NotFound />
    if (isRedirectError(err)) throw err // let the router handle redirects
    return <GenericError error={err} />
  }}
>
  <RouterView />
</ErrorBoundary>

interface ResolvedRoute {
  // ...
  search?: Record<string, unknown> // validated search params (validateSearch)
  isNotFound?: boolean // true when a notFoundComponent fallback rendered
}

import { lazy } from '@pyreon/router'

const routes = [
  {
    path: '/dashboard',
    component: lazy(() => import('./pages/Dashboard'), {
      loading: LoadingSpinner, // shown while loading
      error: LoadError, // shown if all retries fail
    }),
  },
  {
    path: '/settings',
    component: lazy(() => import('./pages/Settings')),
    // No loading or error component -- renders null while loading
  },
]

function lazy(
  loader: () => Promise<ComponentFn | { default: ComponentFn }>,
  options?: { loading?: ComponentFn; error?: ComponentFn },
): LazyComponent

function LoadingSpinner() {
  return <div class="spinner">Loading...</div>
}

function LoadError() {
  return (
    <div class="error">
      <p>Failed to load this page.</p>
      <button onClick={() => window.location.reload()}>Reload</button>
    </div>
  )
}

// Default export (standard ESM module)
lazy(() => import('./pages/Dashboard'))
// The router extracts mod.default

// Direct component export
lazy(() => import('./pages/Dashboard').then((m) => m.DashboardPage))
// The router uses the function directly

const router = createRouter({
  routes,
  scrollBehavior: 'restore',
})

{ path: "/modal", component: Modal, meta: { scrollBehavior: "none" } }
{ path: "/settings", component: Settings, meta: { scrollBehavior: "restore" } }

type ScrollBehaviorFn = (
  to: ResolvedRoute,
  from: ResolvedRoute,
  savedPosition: number | null,
) => 'top' | 'restore' | 'none' | number

const router = createRouter({
  routes,
  scrollBehavior: (to, from, savedPosition) => {
    // Restore position for back/forward navigation
    if (savedPosition !== null) return 'restore'

    // Don't scroll for hash navigation
    if (to.hash) return 'none'

    // Scroll to a specific position
    if (to.path === '/long-page') return 500

    // Default: scroll to top
    return 'top'
  },
})

interface Router {
  /** Navigate to a path or named route */
  push(path: string): Promise<void>
  push(location: {
    name: string
    params?: Record<string, string>
    query?: Record<string, string>
  }): Promise<void>

  /** Replace current history entry */
  replace(path: string): Promise<void>
  replace(location: {
    name: string
    params?: Record<string, string>
    query?: Record<string, string>
  }): Promise<void>

  /** Go back in history */
  back(): void

  /** Go forward in history */
  forward(): void

  /** Navigate by delta steps in history */
  go(delta: number): void

  /** Register a global before-navigation guard. Returns an unregister function. */
  beforeEach(guard: NavigationGuard): () => void

  /** Register a global after-navigation hook. Returns an unregister function. */
  afterEach(hook: AfterEachHook): () => void

  /** Current resolved route (reactive signal -- call it to read) */
  readonly currentRoute: () => ResolvedRoute

  /** True while a navigation (guards + loaders) is in flight */
  readonly loading: () => boolean

  /** Promise that resolves once the initial navigation completes */
  isReady(): Promise<void>

  /**
   * Resolve `path`, load any lazy route components into the cache, and run
   * the matched routes' loaders. After this resolves, a `RouterView`
   * rendered for `path` produces final HTML synchronously. Used by SSR/SSG.
   * `request` is forwarded to loaders as `LoaderContext.request`.
   * `options.skipLoaders: true` resolves lazy components but skips loaders
   * entirely (used by SSG 404 generation, where there's no real request).
   */
  preload(
    path: string,
    request?: Request,
    options?: { skipLoaders?: boolean },
  ): Promise<void>

  /**
   * Run ONLY the matched chain's serverLoaders for `path`, keyed by
   * matched-chain index. Returns the index-keyed data, or a redirect
   * descriptor when a server loader threw redirect(). Server-only —
   * the `serverLoader` fn exists only in the SSR module graph. This is
   * what the single-fetch data endpoint's worker calls.
   */
  runServerLoaders(
    path: string,
    request?: Request,
  ): Promise<
    | { kind: 'data'; data: Record<number, unknown> }
    | { kind: 'redirect'; to: string; status: number }
  >

  /**
   * Invalidate cached loader data. Forces loaders to re-run on next nav.
   *  - no args: invalidate ALL cached loader data
   *  - string: invalidate by cache key (as returned by loaderKey)
   *  - function: invalidate entries where the predicate returns true
   */
  invalidateLoader(keyOrPredicate?: string | ((key: string) => boolean)): void

  /** Remove all event listeners, clear caches, abort in-flight navigations */
  destroy(): void
}

function App() {
  const router = useRouter()

  return (
    <div>
      {router.loading() && <div class="global-loading-bar" />}
      <RouterView />
    </div>
  )
}

const router = createRouter({ routes })

await router.isReady()
mount(<App />, document.getElementById('app')!)

import { parseQuery, parseQueryMulti, stringifyQuery } from '@pyreon/router'

parseQuery('name=Alice&age=30')
// { name: "Alice", age: "30" }

parseQuery('key=value&empty&encoded=%20hello')
// { key: "value", empty: "", encoded: " hello" }

parseQuery('')
// {}

parseQueryMulti('color=red&color=blue&size=lg')
// { color: ["red", "blue"], size: "lg" }

parseQueryMulti('tag=a&tag=b&tag=c')
// { tag: ["a", "b", "c"] }

parseQueryMulti('single=value')
// { single: "value" } -- not wrapped in an array

stringifyQuery({ name: 'Alice', age: '30' })
// "?name=Alice&age=30"

stringifyQuery({ q: 'hello world' })
// "?q=hello%20world"

stringifyQuery({})
// ""

import { resolveRoute, buildPath, findRouteByName } from '@pyreon/router'

const routes = [{ path: '/user/:id', component: User, name: 'user' }]

const resolved = resolveRoute('/user/42?tab=posts#section', routes)
// {
//   path: "/user/42",
//   params: { id: "42" },
//   query: { tab: "posts" },
//   hash: "section",
//   matched: [{ path: "/user/:id", ... }],
//   meta: {}
// }

const resolved = resolveRoute('/nonexistent', routes)
// { path: "/nonexistent", params: {}, query: {}, hash: "", matched: [], meta: {} }

buildPath('/user/:id', { id: '42' })
// "/user/42"

buildPath('/user/:id/posts/:postId', { id: '42', postId: '7' })
// "/user/42/posts/7"

// Splat params preserve slashes
buildPath('/files/:path*', { path: 'docs/readme.md' })
// "/files/docs/readme.md"

const routes = [
  { path: '/', component: Home },
  { path: '/user/:id', component: User, name: 'user' },
  {
    path: '/admin',
    component: Admin,
    children: [{ path: 'settings', component: Settings, name: 'admin-settings' }],
  },
]

findRouteByName('user', routes)
// { path: "/user/:id", component: User, name: "user" }

findRouteByName('admin-settings', routes)
// { path: "settings", component: Settings, name: "admin-settings" }

findRouteByName('nonexistent', routes)
// null

// routes.ts
const routes = [
  { path: '/login', component: LoginPage },
  {
    path: '/dashboard',
    component: DashboardLayout,
    meta: { requiresAuth: true },
    children: [
      { path: 'overview', component: Overview },
      { path: 'settings', component: Settings },
    ],
  },
  { path: '/', redirect: '/dashboard/overview' },
  { path: '(.*)', component: NotFound },
]

// auth.ts
import { createRouter } from '@pyreon/router'

const router = createRouter({ routes, mode: 'history' })

// Global auth guard
router.beforeEach(async (to, from) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    // Save the intended destination for post-login redirect
    sessionStorage.setItem('redirect', to.path)
    return '/login'
  }
})

// After login, redirect to saved destination
async function handleLogin(credentials: Credentials) {
  await authenticate(credentials)
  const redirect = sessionStorage.getItem('redirect') || '/dashboard/overview'
  sessionStorage.removeItem('redirect')
  await router.push(redirect)
}

// Extend RouteMeta
declare module '@pyreon/router' {
  interface RouteMeta {
    requiredRole?: 'admin' | 'editor' | 'viewer'
  }
}

const routes = [
  {
    path: '/admin',
    component: AdminPanel,
    meta: { requiresAuth: true, requiredRole: 'admin' },
    beforeEnter: (to, from) => {
      const user = getCurrentUser()
      if (user?.role !== to.meta.requiredRole) {
        return '/unauthorized'
      }
    },
  },
]

// Extend RouteMeta with breadcrumb labels
declare module '@pyreon/router' {
  interface RouteMeta {
    breadcrumb?: string
  }
}

const routes = [
  {
    path: '/products',
    component: ProductsLayout,
    meta: { breadcrumb: 'Products' },
    children: [
      { path: '', component: ProductList },
      {
        path: ':id',
        component: ProductDetail,
        meta: { breadcrumb: 'Details' },
        children: [{ path: 'reviews', component: ProductReviews, meta: { breadcrumb: 'Reviews' } }],
      },
    ],
  },
]

function Breadcrumbs() {
  const route = useRoute()

  return (
    <nav class="breadcrumbs">
      {route()
        .matched.filter((r) => r.meta?.breadcrumb)
        .map((r, i, arr) => (
          <span>
            {i > 0 && ' / '}
            {i < arr.length - 1 ? (
              <RouterLink to={buildPath(r.path, route().params)}>{r.meta!.breadcrumb}</RouterLink>
            ) : (
              <span>{r.meta!.breadcrumb}</span>
            )}
          </span>
        ))}
    </nav>
  )
}