@pyreon/router 0.14.0 → 0.15.0

package/src/components.tsx

@@ -1,6 +1,15 @@
-import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
-import { createRef, ErrorBoundary, h, onUnmount, provide, useContext } from '@pyreon/core'
-import { signal } from '@pyreon/reactivity'
+import type { ClassValue, ComponentFn, Props, VNodeChild } from '@pyreon/core'
+import {
+  createRef,
+  cx,
+  ErrorBoundary,
+  h,
+  nativeCompat,
+  onUnmount,
+  provide,
+  useContext,
+} from '@pyreon/core'
+import { computed, signal } from '@pyreon/reactivity'
 import { LoaderDataContext, prefetchLoaderData } from './loader'
 import { isLazy, RouterContext, setActiveRouter } from './router'
 import type { LazyComponent, ResolvedRoute, RouteRecord, Router, RouterInstance } from './types'
@@ -75,30 +84,108 @@ export const RouterView: ComponentFn<RouterViewProps> = (props) => {
     router._viewDepth--
   })
 
-  const child = (): VNodeChild => {
-    router._loadingSignal() // reactive — re-renders after lazy load completes
-
-    const route = router.currentRoute()
-
-    if (route.matched.length === 0) return null
-
-    // Render the matched record at this view's depth level
-    const record = route.matched[depth]
-    if (!record) return null // no component at this nesting level
-
-    const cached = router._componentCache.get(record)
-    if (cached) {
-      return renderWithLoader(router, record, cached, route)
-    }
+  // ── Structure / data decoupling ───────────────────────────────────────────
+  //
+  // Pre-fix the reactive child accessor read `_loadingSignal` and the full
+  // `currentRoute` snapshot. The framework's `mountReactive` tears down and
+  // rebuilds the entire subtree on every accessor re-emission, so any
+  // unrelated route signal (loader writes, lazy resolution, navigation
+  // start/end counters, param changes that don't change the matched record)
+  // would tear down the layout, then the page, then everything below it.
+  // For a single page load with one cold-start `router.replace()`, that
+  // produced ~9 cascading remounts of the layout — confirmed empirically
+  // by instance counters.
+  //
+  // The fix decouples STRUCTURE (which RouteRecord is mounted at this depth
+  // + which component to render for it) from DATA (params / query / loader
+  // data flowing into the rendered component). One computed returns BOTH
+  // the record and its resolved component as an atomic pair — re-emits ONLY
+  // when either side changes (reference equality on both fields). Loader
+  // writes / param changes / navigation counters don't re-emit; the rendered
+  // component receives route data through reactive props + the
+  // `LoaderDataProvider` context, which subscribe per-component to the
+  // signals they actually care about, so a param change re-renders just the
+  // page leaf — not the layout chain above it.
+  //
+  // The structure is intentionally a SINGLE computed (not two layered ones):
+  // when `currentRoute` changes, the reactive child accessor must see a
+  // CONSISTENT (rec, comp) pair on its next re-run. With two layered
+  // computeds the child accessor subscribes to both, and the order in which
+  // those two notify the child is unspecified — if the child runs after rec
+  // is notified but before comp re-evaluates, it reads the new rec paired
+  // with the OLD comp. Empirically that produced rec=/button paired with
+  // comp=HomePage, leaving the previous page rendered after navigation.
+  // Combining them into one computed forces atomic emission.
+  interface DepthEntry {
+    rec: RouteRecord | null
+    comp: ComponentFn | null
+    /**
+     * True when lazy resolution exhausted retries and the chunk is in
+     * `_erroredChunks`. Tracked structurally so the entry re-emits when
+     * the error state flips on — otherwise `equals` would block the
+     * { rec, comp: null } → { rec, comp: null, errored: true } transition
+     * (`comp` and `rec` are unchanged) and the error component would
+     * never render.
+     */
+    errored: boolean
+    /**
+     * The full ResolvedRoute reference at the time this entry was emitted.
+     * `currentRoute` is a `computed` keyed on `currentPath` — same path
+     * returns the same memoized reference, different path returns a new
+     * one. Tracking the reference in `equals` makes the depth re-emit on
+     * any real navigation (params change, query change, hash change) even
+     * when the matched record at this depth stays the same — required so
+     * `/user/42 → /user/99` re-renders the User component with new params
+     * — while NOT re-emitting on navigate-flow noise (`_loadingSignal`
+     * start/end ticks, lazy resolution writes that complete without
+     * changing currentPath). One emit per real navigation, not per
+     * within-navigation signal tick.
+     */
+    route: ResolvedRoute
+  }
+  const depthEntry = computed<DepthEntry>(
+    () => {
+      const route = router.currentRoute()
+      const rec = route.matched[depth] ?? null
+      if (!rec) return { rec: null, comp: null, errored: false, route }
+      // Subscribe to `_loadingSignal` so lazy resolution wakes this
+      // computed up — when the cache fills, we re-emit with comp set.
+      router._loadingSignal()
+      const errored = router._erroredChunks.has(rec)
+      if (errored) return { rec, comp: null, errored: true, route }
+      const cached = router._componentCache.get(rec)
+      if (cached) return { rec, comp: cached, errored: false, route }
+      const raw = rec.component
+      if (!isLazy(raw)) {
+        cacheSet(router, rec, raw)
+        return { rec, comp: raw, errored: false, route }
+      }
+      // Lazy and not yet cached — `child()` below renders the lazy
+      // fallback and triggers the load; once the load completes,
+      // `_loadingSignal` ticks and this computed re-emits with `comp` set.
+      return { rec, comp: null, errored: false, route }
+    },
+    {
+      equals: (a, b) =>
+        a.rec === b.rec &&
+        a.comp === b.comp &&
+        a.errored === b.errored &&
+        a.route === b.route,
+    },
+  )
 
-    const raw = record.component
+  const child = (): VNodeChild => {
+    const { rec, comp, route } = depthEntry()
+    if (!rec) return null
 
-    if (!isLazy(raw)) {
-      cacheSet(router, record, raw)
-      return renderWithLoader(router, record, raw, route)
+    if (comp) {
+      return renderWithLoader(router, rec, comp, route)
     }
 
-    return renderLazyRoute(router, record, raw)
+    // Component not yet cached — kick off the lazy load. `renderLazyRoute`
+    // mutates `_loadingSignal` and `_componentCache` on completion, which
+    // re-emits `depthEntry` and re-runs this accessor with `comp` set.
+    return renderLazyRoute(router, rec, rec.component as LazyComponent)
   }
 
   return h('div', { 'data-pyreon-router-view': true }, child as unknown as VNodeChild)
@@ -155,7 +242,14 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
   }
 
   const inst = router as RouterInstance | null
-  const href = inst?.mode === 'history' ? `${inst._base}${props.to}` : `#${props.to}`
+  // `href` MUST be an accessor, not a string captured at setup. `props.to`
+  // is a getter when the parent passes a reactive expression (the JSX
+  // compiler wraps `<RouterLink to={someExpr}>` as `_rp(() => someExpr)`).
+  // Capturing into a string at setup time freezes the URL — passing the
+  // accessor lets `applyProp` wrap it in `renderEffect` so href tracks the
+  // underlying signal.
+  const href = (): string =>
+    inst?.mode === 'history' ? `${inst._base}${props.to}` : `#${props.to}`
 
   const isExactMatch = (): boolean => {
     if (!router) return false
@@ -199,12 +293,44 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
     onUnmount(() => observer.disconnect())
   }
 
-  // Forward all non-RouterLink props (style, class, id, data-*, etc.) to the <a>.
-  const { to: _to, replace: _replace, activeClass: _ac, exactActiveClass: _eac, exact: _exact, prefetch: _prefetch, children, ...rest } = props
+  // Forward all non-RouterLink props (style, id, data-*, etc.) to the <a>.
+  // `class` is pulled out separately so it can be MERGED with the internal
+  // active-class accessor — overriding the user's class silently dropped any
+  // conditional class the consumer wanted (e.g. `class={() => cond ? 'on' : ''}`).
+  const {
+    to: _to,
+    replace: _replace,
+    activeClass: _ac,
+    exactActiveClass: _eac,
+    exact: _exact,
+    prefetch: _prefetch,
+    class: userClass,
+    children,
+    ...rest
+  } = props as RouterLinkProps & { class?: ClassValue | (() => ClassValue) }
+
+  // Compose the user-provided `class` (string / array / object / function) with
+  // the internal `activeClass` accessor. Returning a function lets `applyProp`
+  // wrap it in `renderEffect` once — so navigation re-evaluates BOTH sides on
+  // every route change without rebuilding the link.
+  const mergedClass = (): string => {
+    const userResolved =
+      typeof userClass === 'function' ? (userClass as () => ClassValue)() : userClass
+    return cx([userResolved, activeClass()] as ClassValue)
+  }
 
   return h(
     'a',
-    { ...rest, ref, href, class: activeClass, 'aria-current': ariaCurrent, onClick: handleClick, onMouseEnter: handleMouseEnter, onFocus: handleFocus },
+    {
+      ...rest,
+      ref,
+      href,
+      class: mergedClass,
+      'aria-current': ariaCurrent,
+      onClick: handleClick,
+      onMouseEnter: handleMouseEnter,
+      onFocus: handleFocus,
+    },
     children ?? props.to,
   )
 }
@@ -455,3 +581,12 @@ function isStaleChunk(err: unknown): boolean {
   if (err instanceof SyntaxError) return true
   return false
 }
+
+// Mark router framework components as native — compat-mode jsx() runtimes
+// (react/preact/vue/solid-compat) skip wrapCompatComponent for these so their
+// provide() / useContext() / onUnmount() / effect() / IntersectionObserver
+// setup runs inside Pyreon's lifecycle frame instead of the compat wrapper's
+// runUntracked accessor.
+nativeCompat(RouterProvider)
+nativeCompat(RouterView)
+nativeCompat(RouterLink)

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal process type — just enough for `process.env.NODE_ENV` checks.
+ * Avoids requiring @types/node in consumers that import pyreon source
+ * via the `"bun"` export condition.
+ */
+declare var process: { env: { NODE_ENV?: string } }

package/src/index.ts

@@ -46,6 +46,8 @@ export type { RouterLinkProps, RouterProviderProps, RouterViewProps } from './co
 export { RouterLink, RouterProvider, RouterView } from './components'
 export type { NotFoundBoundaryProps } from './not-found'
 export { isNotFoundError, NotFoundBoundary, notFound } from './not-found'
+export type { RedirectStatus } from './redirect'
+export { getRedirectInfo, isRedirectError, redirect } from './redirect'
 export { hydrateLoaderData, prefetchLoaderData, serializeLoaderData, useLoaderData } from './loader'
 // Match utilities (useful for SSR route pre-fetching)
 export {

package/src/loader.ts

@@ -3,8 +3,7 @@ import { createContext, useContext } from '@pyreon/core'
 import type { RouterInstance } from './types'
 
 // Dev-mode gate + counter sink. See packages/internals/perf-harness for contract.
-// @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-const __DEV__ = import.meta.env?.DEV === true
+const __DEV__ = process.env.NODE_ENV !== 'production'
 const _countSink = globalThis as { __pyreon_count__?: (name: string, n?: number) => void }
 
 /**
@@ -33,12 +32,22 @@ export function useLoaderData<T = unknown>(): T {
  * SSR helper: pre-run all loaders for the given path before rendering.
  * Call this before `renderToString` so route components can read data via `useLoaderData()`.
  *
+ * The optional `request` is forwarded to each loader's `LoaderContext.request`,
+ * letting server-side loaders read cookies / auth headers and `throw redirect()`
+ * before the layout renders. A loader that throws `redirect()` propagates the
+ * thrown error here — the SSR handler's `catch` converts it into a 302/307
+ * `Location:` Response.
+ *
  * @example
  * const router = createRouter({ routes, url: req.url })
- * await prefetchLoaderData(router, req.url)
+ * await prefetchLoaderData(router, req.url, request)
  * const html = await renderToString(h(App, { router }))
  */
-export async function prefetchLoaderData(router: RouterInstance, path: string): Promise<void> {
+export async function prefetchLoaderData(
+  router: RouterInstance,
+  path: string,
+  request?: Request,
+): Promise<void> {
   if (__DEV__) _countSink.__pyreon_count__?.('router.prefetch')
   const route = router._resolve(path)
   // Use a local AbortController — prefetch is best-effort and must NOT
@@ -54,6 +63,7 @@ export async function prefetchLoaderData(router: RouterInstance, path: string):
           params: route.params,
           query: route.query,
           signal: ac.signal,
+          ...(request ? { request } : {}),
         })
         router._loaderData.set(r, data)
       }),

package/src/manifest.ts

@@ -254,6 +254,69 @@ const User = () => {
 }`,
       seeAlso: ['useMiddlewareData', 'useRoute'],
     },
+    {
+      name: 'redirect',
+      kind: 'function',
+      signature: 'redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): never',
+      summary:
+        "Throw inside a route loader to redirect the navigation BEFORE the layout renders. On SSR (initial nav), the thrown error is converted by `@pyreon/server`'s handler into a real HTTP `302`/`307` `Location:` response — no layout HTML leaves the server. On CSR (subsequent nav), the redirect propagates through the navigate flow and triggers `router.replace()` before any matched route's component mounts. Replaces the fragile `onMount + router.push()` workaround for auth-gates under nested-layout dev SSR + hydration. Default status is `307` (Temporary Redirect, method-preserving).",
+      example: `// src/routes/app/_layout.tsx
+import { redirect, type LoaderContext } from "@pyreon/router"
+
+export async function loader(ctx: LoaderContext) {
+  // SSR: read from request headers; CSR: read from document.cookie
+  const cookie = ctx.request?.headers.get("cookie")
+    ?? (typeof document !== "undefined" ? document.cookie : "")
+  const sid = /(?:^|;\\s*)sid=([^;]+)/.exec(cookie)?.[1]
+  if (!sid) redirect("/login")
+  const session = await getSession(sid)
+  if (!session) redirect("/login")
+  return { session }
+}`,
+      mistakes: [
+        'Calling `redirect()` outside a loader (in a component body, an event handler, etc.) — the helper expects to be caught by the loader-runner. For imperative redirects from event handlers, use `router.replace(target)` instead.',
+        "Forgetting to make `LoaderContext.request` access optional. It's populated only on SSR; CSR loaders see `request: undefined`. Read both: `ctx.request?.headers.get('cookie') ?? document.cookie`.",
+        'Using `redirect()` for control-flow that should be a `<Match>` / `<Show>` conditional — the helper is for redirecting the URL, not for branching the rendered output.',
+        'Returning `redirect()` instead of throwing it. The helper has return type `never` and throws — `return redirect(...)` is misleading and may suppress the throw under TS strict-null checks.',
+        'Picking the wrong status. Default `307` preserves the request method (POST stays POST after redirect). Use `302`/`303` to force GET on the target. Use `301`/`308` for PERMANENT moves (browsers cache them aggressively).',
+        'Assuming `redirect()` cancels every loader in a sibling chain. The first loader to throw wins; later loaders in the same `Promise.allSettled` batch may have already started executing before the redirect short-circuits. Treat them as best-effort.',
+      ],
+      seeAlso: ['notFound', 'useLoaderData', 'isRedirectError'],
+    },
+    {
+      name: 'isRedirectError',
+      kind: 'function',
+      signature: 'isRedirectError(err: unknown): boolean',
+      summary:
+        'Type guard for errors thrown by `redirect()`. Used internally by the router (CSR) and `@pyreon/server` (SSR) to distinguish redirect-control-flow errors from real failures. Useful in custom error boundaries that should let redirects pass through to the framework instead of catching them.',
+      example: `import { ErrorBoundary } from "@pyreon/core"
+import { isRedirectError } from "@pyreon/router"
+
+<ErrorBoundary fallback={(err, reset) => {
+  if (isRedirectError(err)) throw err  // let the framework handle it
+  return <ErrorPage error={err} onReset={reset} />
+}}>
+  <App />
+</ErrorBoundary>`,
+      seeAlso: ['redirect', 'isNotFoundError', 'getRedirectInfo'],
+    },
+    {
+      name: 'getRedirectInfo',
+      kind: 'function',
+      signature: 'getRedirectInfo(err: unknown): { url: string; status: 301 | 302 | 303 | 307 | 308 } | null',
+      summary:
+        "Extract the redirect URL and status from a thrown RedirectError. Returns `null` for non-redirect errors. Used by `@pyreon/server`'s SSR handler to convert the thrown error into a 302/307 `Response`.",
+      example: `import { getRedirectInfo } from "@pyreon/router"
+
+try {
+  await prefetchLoaderData(router, path, request)
+} catch (err) {
+  const info = getRedirectInfo(err)
+  if (info) return new Response(null, { status: info.status, headers: { Location: info.url } })
+  throw err
+}`,
+      seeAlso: ['redirect', 'isRedirectError'],
+    },
     {
       name: 'useSearchParams',
       kind: 'hook',

package/src/match.ts

@@ -293,7 +293,18 @@ function flattenOne(
     return
   }
 
-  const joined = [...parentSegments, ...c.segments]
+  // fs-router emits absolute paths for nested children (e.g. parent
+  // `/app` with child `/app/dashboard`, NOT child `dashboard`). Concating
+  // parent segments with the child's already-absolute segments would
+  // produce `/app/app/dashboard` — the staticMap then lookups the wrong
+  // key and resolveRoute returns `matched: []` for any such request.
+  // Detect "child path is absolute" (`path` starts with `/`) and skip the
+  // parent-segment prefix in that case — the child's own segments ARE
+  // the full intended path. Relative children (`dashboard`, `:id`)
+  // continue to inherit the parent's segments via concatenation.
+  const childPath = c.route.path
+  const isAbsoluteChild = typeof childPath === 'string' && childPath.startsWith('/')
+  const joined = isAbsoluteChild ? c.segments : [...parentSegments, ...c.segments]
   if (c.children && c.children.length > 0) {
     flattenWalk(result, c.children, joined, chain, meta)
   }

package/src/redirect.ts

@@ -0,0 +1,63 @@
+// ─── Redirect symbol + throw ────────────────────────────────────────────────
+
+const REDIRECT = Symbol.for('pyreon.redirect')
+
+/** Standard redirect status codes. 307/308 preserve the request method, 302/303 don't. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308
+
+interface RedirectInfo {
+  url: string
+  status: RedirectStatus
+}
+
+/**
+ * Throw inside a route loader to redirect the navigation server-side
+ * (during SSR returns a 302/307 `Location:` response) and client-side
+ * (during CSR triggers `router.replace()` before the layout renders).
+ *
+ * The auth-gate use case: replaces the fragile `onMount + router.push()`
+ * workaround. `onMount` doesn't fire reliably under nested-layout dev SSR +
+ * hydration — so the layout renders briefly before the push happens, leaking
+ * authenticated UI to unauthenticated users. `redirect()` runs in the loader
+ * BEFORE the layout's component is invoked, so the unauthenticated UI never
+ * mounts in the first place.
+ *
+ * @example
+ * ```ts
+ * // src/routes/app/_layout.tsx
+ * export const loader = async ({ request }) => {
+ *   const session = await getSession(request)
+ *   if (!session) redirect('/login')
+ *   return { user: session.user }
+ * }
+ * ```
+ *
+ * @param url - Target URL (typically a path like `/login` or absolute URL for cross-origin).
+ * @param status - HTTP redirect status. Default `307` (Temporary Redirect, method-preserving).
+ *   Use `301`/`308` for permanent moves, `302`/`303` to force GET on the target.
+ */
+export function redirect(url: string, status: RedirectStatus = 307): never {
+  const err = new Error(`Redirect to ${url}`)
+  ;(err as unknown as Record<symbol, RedirectInfo>)[REDIRECT] = { url, status }
+  throw err
+}
+
+/** Check if an error is a RedirectError thrown by `redirect()`. */
+export function isRedirectError(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    typeof (err as Record<symbol, unknown>)[REDIRECT] === 'object'
+  )
+}
+
+/**
+ * Extract the redirect URL and status from a thrown RedirectError. Returns
+ * `null` if `err` isn't a RedirectError. Used by the router's loader-runner
+ * (CSR) and the SSR handler to convert the thrown error into the right kind
+ * of response (a `router.replace()` call or a `302`/`307` Response).
+ */
+export function getRedirectInfo(err: unknown): RedirectInfo | null {
+  if (!isRedirectError(err)) return null
+  return (err as Record<symbol, RedirectInfo>)[REDIRECT] ?? null
+}