@pyreon/router 0.14.0 → 0.16.0

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import * as _pyreon_core0 from "@pyreon/core";
+import * as _$_pyreon_core0 from "@pyreon/core";
 import { ComponentFn, ComponentFn as ComponentFn$1, Props, VNodeChild } from "@pyreon/core";
 import { Computed, Signal } from "@pyreon/reactivity";
 
@@ -56,6 +56,15 @@ interface ResolvedRoute<P extends Record<string, string | undefined> = Record<st
   search?: Record<string, unknown> | undefined;
   /** Middleware data attached during navigation (populated by middleware chain) */
   _middlewareData?: Record<string, unknown> | undefined;
+  /**
+   * `true` when the URL didn't match any route AND a parent record's
+   * `notFoundComponent` was used as a synthetic fallback leaf. The
+   * `matched` chain ends with a synthetic `RouteRecord` rendering the
+   * not-found component INSIDE all its ancestor layouts — so 404 pages
+   * carry the same chrome (headers, footers, navigation) as regular
+   * pages. SSR handlers read this to set HTTP status 404.
+   */
+  isNotFound?: boolean;
 }
 declare const LAZY_SYMBOL: unique symbol;
 interface LazyComponent {
@@ -111,6 +120,21 @@ interface LoaderContext {
   query: Record<string, string>;
   /** Aborted when a newer navigation supersedes this one */
   signal: AbortSignal;
+  /**
+   * The incoming HTTP `Request` — populated only when the loader runs during
+   * SSR (via `prefetchLoaderData`); `undefined` on every CSR navigation.
+   * Lets server-side loaders read cookies / auth headers and decide whether
+   * to `throw redirect('/login')` BEFORE the layout renders.
+   *
+   * @example
+   * loader: ({ request }) => {
+   *   const cookie = request?.headers.get('cookie') ?? ''
+   *   const sid = cookie.match(/sid=([^;]+)/)?.[1]
+   *   if (!sid) redirect('/login')
+   *   return { sid }
+   * }
+   */
+  request?: Request;
 }
 type RouteLoaderFn = (ctx: LoaderContext) => Promise<unknown>;
 interface RouteRecord<TPath extends string = string> {
@@ -172,6 +196,14 @@ interface RouteRecord<TPath extends string = string> {
   gcTime?: number;
   /** Component rendered when this route's loader throws an error */
   errorComponent?: ComponentFn$1;
+  /**
+   * Component rendered when a URL doesn't match any descendant route under
+   * this record's path. Acts as a "404 within layout" — the matched chain
+   * is `[...ancestors, this, syntheticLeaf]` so the not-found component
+   * renders INSIDE this layout's chrome. fs-router attaches this when it
+   * detects a `_404.tsx` / `_not-found.tsx` file under this layout.
+   */
+  notFoundComponent?: ComponentFn$1;
   /**
    * Component rendered while this route's loader is running.
    * Only shown after `pendingMs` (default: 0) to avoid flash on fast loads.
@@ -313,7 +345,9 @@ interface Router<TNames extends string = string> {
    * separately when creating the router (`createRouter({ url, ... })`) or
    * call this for the same `url` you initialised the router with.
    */
-  preload(path: string): Promise<void>;
+  preload(path: string, request?: Request, options?: {
+    skipLoaders?: boolean;
+  }): Promise<void>;
   /**
    * Invalidate cached loader data. Forces loaders to re-run on next navigation.
    * - No args: invalidate ALL cached loader data
@@ -363,8 +397,18 @@ interface RouterInstance extends Router {
     data: unknown;
     timestamp: number;
   }>;
-  /** In-flight loader dedup: cacheKey → Promise */
-  _loaderInflight: Map<string, Promise<unknown>>;
+  /**
+   * In-flight loader dedup: cacheKey → { promise, signal }.
+   * Tracking the signal lets dedup skip an in-flight entry whose signal is
+   * already aborted — otherwise nav-2 would inherit nav-1's aborted promise
+   * (`router.push` aborts the previous nav's controller before starting the
+   * next, so back-to-back nav to the same path could resolve nav-2 against
+   * nav-1's aborted fetch).
+   */
+  _loaderInflight: Map<string, {
+    promise: Promise<unknown>;
+    signal: AbortSignal;
+  }>;
 }
 //#endregion
 //#region src/components.d.ts
@@ -460,6 +504,50 @@ interface NotFoundBoundaryProps extends Props {
  */
 declare const NotFoundBoundary: ComponentFn<NotFoundBoundaryProps>;
 //#endregion
+//#region src/redirect.d.ts
+/** Standard redirect status codes. 307/308 preserve the request method, 302/303 don't. */
+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.
+ */
+declare function redirect(url: string, status?: RedirectStatus): never;
+/** Check if an error is a RedirectError thrown by `redirect()`. */
+declare function isRedirectError(err: unknown): boolean;
+/**
+ * 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).
+ */
+declare function getRedirectInfo(err: unknown): RedirectInfo | null;
+//#endregion
 //#region src/loader.d.ts
 /**
  * Returns the data resolved by the current route's `loader` function.
@@ -478,12 +566,18 @@ declare 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 }))
  */
-declare function prefetchLoaderData(router: RouterInstance, path: string): Promise<void>;
+declare function prefetchLoaderData(router: RouterInstance, path: string, request?: Request): Promise<void>;
 /**
  * Serialize loader data to a JSON-safe plain object for embedding in SSR HTML.
  * Keys are route path patterns (stable across server and client).
@@ -496,6 +590,35 @@ declare function prefetchLoaderData(router: RouterInstance, path: string): Promi
  *   ...${html}...`
  */
 declare function serializeLoaderData(router: RouterInstance): Record<string, unknown>;
+/**
+ * Serialize loader data to JSON for embedding in an SSR `<script>` tag.
+ *
+ * M2.2 — Drop-in replacement for `JSON.stringify(serializeLoaderData(router))`
+ * with three correctness wins:
+ *   1. **Strips functions / symbols / undefined values silently** so a loader
+ *      that accidentally returns `{ data, fn: () => {} }` doesn't crash
+ *      hydration — `JSON.stringify` drops these by default for the value
+ *      itself but THROWS on circular references containing them. The custom
+ *      replacer drops them inline so the surrounding object survives.
+ *   2. **Detects circular references** with a WeakSet and emits a clear
+ *      `[Pyreon] Loader returned circular reference at key "<path>"` error
+ *      naming the offending key instead of `Converting circular structure
+ *      to JSON` (which doesn't tell the user which loader is broken).
+ *   3. **Escapes `</`** so embedding the JSON inside `<script>` can't break
+ *      out of the script tag — already done at every call site but now
+ *      centralised so all four callers (handler string-mode, handler stream-
+ *      mode, SSG entry, dev SSR) get the escape uniformly.
+ *
+ * Returns the safely-escaped JSON string ready to drop into a `<script>`
+ * tag's body. Throws (with the Pyreon-prefixed error) on circular refs so
+ * the caller's existing try/catch wraps it correctly — silent serialization
+ * failures were the pre-fix shape.
+ *
+ * @example
+ * const json = stringifyLoaderData(serializeLoaderData(router))
+ * const tag = `<script>window.__PYREON_LOADER_DATA__=${json}</script>`
+ */
+declare function stringifyLoaderData(loaderData: Record<string, unknown>): string;
 /**
  * Hydrate loader data from a serialized object (e.g. `window.__PYREON_LOADER_DATA__`).
  * Populates the router's internal `_loaderData` map so the initial render uses
@@ -533,7 +656,7 @@ declare function buildPath(pattern: string, params: Record<string, string>): str
 declare function findRouteByName(name: string, routes: RouteRecord[]): RouteRecord | null;
 //#endregion
 //#region src/router.d.ts
-declare const RouterContext: _pyreon_core0.Context<RouterInstance | null>;
+declare const RouterContext: _$_pyreon_core0.Context<RouterInstance | null>;
 declare function useRouter(): Router;
 declare function useRoute<TPath extends string = string>(): () => ResolvedRoute<ExtractParams<TPath> & Record<string, string>, Record<string, string>>;
 /**
@@ -688,5 +811,5 @@ declare function useTransition(): () => boolean;
 declare function useMiddlewareData(): () => Record<string, unknown>;
 declare function createRouter<TNames extends string = string>(options: RouterOptions | RouteRecord[]): Router<TNames>;
 //#endregion
-export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, NotFoundBoundary, type NotFoundBoundaryProps, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, hydrateLoaderData, isNotFoundError, lazy, notFound, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, resolveRoute, serializeLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams, useValidatedSearch };
+export { type AfterEachHook, type Blocker, type BlockerFn, type ExtractParams, type LazyComponent, type LoaderContext, type NavigationGuard, type NavigationGuardResult, NotFoundBoundary, type NotFoundBoundaryProps, type RedirectStatus, type ResolvedRoute, type RouteComponent, type RouteLoaderFn, type RouteMeta, type RouteMiddleware, type RouteMiddlewareContext, type RouteRecord, type Router, RouterContext, RouterLink, type RouterLinkProps, type RouterOptions, RouterProvider, type RouterProviderProps, RouterView, type RouterViewProps, type ScrollBehaviorFn, buildPath, createRouter, findRouteByName, getRedirectInfo, hydrateLoaderData, isNotFoundError, isRedirectError, lazy, notFound, onBeforeRouteLeave, onBeforeRouteUpdate, parseQuery, parseQueryMulti, prefetchLoaderData, redirect, resolveRoute, serializeLoaderData, stringifyLoaderData, stringifyQuery, useBlocker, useIsActive, useLoaderData, useMiddlewareData, useRoute, useRouter, useSearchParams, useTransition, useTypedSearchParams, useValidatedSearch };
 //# sourceMappingURL=index2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/router",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Official router for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/router#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "!lib/**/*.map",
     "src",
     "README.md",
     "LICENSE"
@@ -43,14 +44,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.14.0",
-    "@pyreon/reactivity": "^0.14.0",
-    "@pyreon/runtime-dom": "^0.14.0"
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0",
+    "@pyreon/runtime-dom": "^0.16.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/test-utils": "^0.13.2",
+    "@pyreon/test-utils": "^0.13.3",
     "@vitest/browser-playwright": "^4.1.4",
     "happy-dom": "^20.8.3"
   }

package/src/components.tsx

@@ -1,7 +1,17 @@
-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 { _setDefaultChromeLayout } from './match'
 import { isLazy, RouterContext, setActiveRouter } from './router'
 import type { LazyComponent, ResolvedRoute, RouteRecord, Router, RouterInstance } from './types'
 
@@ -75,30 +85,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 +243,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 +294,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 +582,41 @@ 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)
+
+// ─── DefaultChromeLayout ─────────────────────────────────────────────────────
+//
+// Synthetic layout used by the layout-less-app 404 fallback. When the user
+// has a page-level `notFoundComponent` (`_404.tsx` at the route root without
+// a wrapping `_layout.tsx`), `findNotFoundFallback` in match.ts synthesizes
+// a chain `[DefaultChromeLayout, syntheticLeaf]` and the render pipeline
+// produces 404 HTML wrapped in `<main data-pyreon-default-chrome>` instead
+// of the bare component output.
+//
+// The wrapper is intentionally minimal:
+//   - `<main>` provides a semantic landmark for accessibility and SEO.
+//   - The `data-pyreon-default-chrome` attribute lets users target the
+//     wrapper from CSS if they want to customize spacing / centering.
+//   - No prescribed visual styling — the framework can't know the user's
+//     design system, so we ship semantics only.
+//
+// Registered via the setter pattern (`_setDefaultChromeLayout`) instead of
+// directly imported into match.ts to avoid a circular dependency: components.tsx
+// depends transitively on match.ts (via router.ts), so match.ts can't import
+// components.tsx without a cycle. The setter call runs at module load —
+// every Pyreon app imports something from `./components.tsx` (RouterProvider,
+// RouterView, RouterLink), which triggers the setter before any resolveRoute
+// call can fire.
+export const DefaultChromeLayout: ComponentFn = () =>
+  h('main', { 'data-pyreon-default-chrome': '' }, h(RouterView, null))
+
+nativeCompat(DefaultChromeLayout)
+_setDefaultChromeLayout(DefaultChromeLayout)

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,7 +46,15 @@ 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 { hydrateLoaderData, prefetchLoaderData, serializeLoaderData, useLoaderData } from './loader'
+export type { RedirectStatus } from './redirect'
+export { getRedirectInfo, isRedirectError, redirect } from './redirect'
+export {
+  hydrateLoaderData,
+  prefetchLoaderData,
+  serializeLoaderData,
+  stringifyLoaderData,
+  useLoaderData,
+} from './loader'
 // Match utilities (useful for SSR route pre-fetching)
 export {
   buildPath,

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)
       }),
@@ -79,6 +89,64 @@ export function serializeLoaderData(router: RouterInstance): Record<string, unkn
   return result
 }
 
+/**
+ * Serialize loader data to JSON for embedding in an SSR `<script>` tag.
+ *
+ * M2.2 — Drop-in replacement for `JSON.stringify(serializeLoaderData(router))`
+ * with three correctness wins:
+ *   1. **Strips functions / symbols / undefined values silently** so a loader
+ *      that accidentally returns `{ data, fn: () => {} }` doesn't crash
+ *      hydration — `JSON.stringify` drops these by default for the value
+ *      itself but THROWS on circular references containing them. The custom
+ *      replacer drops them inline so the surrounding object survives.
+ *   2. **Detects circular references** with a WeakSet and emits a clear
+ *      `[Pyreon] Loader returned circular reference at key "<path>"` error
+ *      naming the offending key instead of `Converting circular structure
+ *      to JSON` (which doesn't tell the user which loader is broken).
+ *   3. **Escapes `</`** so embedding the JSON inside `<script>` can't break
+ *      out of the script tag — already done at every call site but now
+ *      centralised so all four callers (handler string-mode, handler stream-
+ *      mode, SSG entry, dev SSR) get the escape uniformly.
+ *
+ * Returns the safely-escaped JSON string ready to drop into a `<script>`
+ * tag's body. Throws (with the Pyreon-prefixed error) on circular refs so
+ * the caller's existing try/catch wraps it correctly — silent serialization
+ * failures were the pre-fix shape.
+ *
+ * @example
+ * const json = stringifyLoaderData(serializeLoaderData(router))
+ * const tag = `<script>window.__PYREON_LOADER_DATA__=${json}</script>`
+ */
+export function stringifyLoaderData(loaderData: Record<string, unknown>): string {
+  const seen = new WeakSet<object>()
+  const keyStack: string[] = []
+  const replacer = (key: string, value: unknown): unknown => {
+    // JSON.stringify calls the replacer with key = '' for the root, then
+    // the property name for each subsequent member. Track the path so the
+    // circular-ref error message names the offending route key.
+    if (key !== '') keyStack.push(key)
+    if (typeof value === 'function' || typeof value === 'symbol') {
+      // Drop silently. JSON.stringify already drops these as VALUES, but
+      // an explicit drop also handles array entries (where it'd convert
+      // to null otherwise — undesirable for downstream typed hydration).
+      return undefined
+    }
+    if (value && typeof value === 'object') {
+      if (seen.has(value as object)) {
+        const path = keyStack.join('.') || '<root>'
+        throw new Error(
+          `[Pyreon] Loader returned circular reference at "${path}". ` +
+            `Loaders must return JSON-serializable data (no cycles, no functions, no Date/Map/Set without a custom replacer). ` +
+            `Common cause: returning a Mongo/Prisma model with back-references intact.`,
+        )
+      }
+      seen.add(value as object)
+    }
+    return value
+  }
+  return JSON.stringify(loaderData, replacer).replace(/<\//g, '<\\/')
+}
+
 /**
  * Hydrate loader data from a serialized object (e.g. `window.__PYREON_LOADER_DATA__`).
  * Populates the router's internal `_loaderData` map so the initial render uses