one 1.9.7 → 1.9.8

package/src/createApp.tsx

@@ -164,6 +164,12 @@ export function createApp(options: CreateAppProps) {
     initClientMatches(serverContext.matches)
   }
 
+  // NOTE: for SSG 404 pages, we DON'T set notFoundState before initial render
+  // because the server rendered the +not-found page through normal routing
+  // setting notFoundState would cause useSlot to skip the layout hierarchy,
+  // leading to hydration mismatch
+  // notFoundState is only set for client-side navigations that result in 404
+
   // Wait for setup file to complete first (if provided)
   // This ensures setup code (error handlers, analytics, etc.) runs before the app
   // The function is called here at runtime, not at module evaluation time during build
@@ -181,6 +187,22 @@ export function createApp(options: CreateAppProps) {
       })
     : [options.routes[`/${options.routerRoot}/_layout.tsx`]?.()]
 
+  // for 404 pages, use history.state.__tempLocation to route to notFoundPath
+  // without changing the browser URL. the router checks __tempLocation and uses
+  // that path for routing instead of the URL. this ensures hydration matches
+  // the server-rendered +not-found page while keeping the original URL intact
+  const one404Marker = (window as any).__one404
+  if (one404Marker?.notFoundPath) {
+    const currentState = window.history.state || {}
+    window.history.replaceState(
+      {
+        ...currentState,
+        __tempLocation: { pathname: one404Marker.notFoundPath, search: '' },
+      },
+      ''
+    )
+  }
+
   return setupComplete
     .then(() => Promise.all(preloadPromises))
     .then(() => {

package/src/createHandleRequest.test.ts

@@ -140,10 +140,18 @@ describe('createHandleRequest', () => {
       expect(result).toBeNull()
     })
 
-    it('should skip paths starting with /@', async () => {
+    it('should skip vite internal paths like /@fs/', async () => {
       const { handler } = createHandleRequest(mockHandlers, { routerRoot: '/app' })
-      const result = await handler(createRequest('/@fs/some/path'))
-      expect(result).toBeNull()
+      expect(await handler(createRequest('/@fs/some/path'))).toBeNull()
+      expect(await handler(createRequest('/@vite/client'))).toBeNull()
+      expect(await handler(createRequest('/@id/__x00__virtual:one-entry'))).toBeNull()
+    })
+
+    it('should NOT skip user routes that start with @', async () => {
+      const { handler } = createHandleRequest(mockHandlers, { routerRoot: '/app' })
+      // routes like /@admin should be matched, not skipped
+      await handler(createRequest('/@admin'))
+      expect(mockHandlers.handlePage).toHaveBeenCalled()
     })
   })
 })

package/src/createHandleRequest.ts

@@ -302,7 +302,9 @@ export function createHandleRequest(
       // skip paths handled by vite internals or react native dev middleware
       if (
         pathname === '/__vxrnhmr' ||
-        pathname.startsWith('/@') ||
+        pathname.startsWith('/@vite/') ||
+        pathname.startsWith('/@fs/') ||
+        pathname.startsWith('/@id/') ||
         pathname.startsWith('/debugger-frontend') ||
         pathname.startsWith('/inspector')
       ) {

package/src/notFoundState.ts

@@ -0,0 +1,158 @@
+import * as React from 'react'
+import type { RouteNode } from './router/Route'
+
+// state for inline not-found rendering
+export interface NotFoundState {
+  // path to the +not-found route to render
+  notFoundPath: string
+  // the route node to render
+  notFoundRouteNode?: RouteNode
+  // original path that triggered the 404
+  originalPath: string
+}
+
+// global not-found state
+let currentNotFoundState: NotFoundState | null = null
+const notFoundListeners = new Set<() => void>()
+
+export function getNotFoundState(): NotFoundState | null {
+  return currentNotFoundState
+}
+
+export function setNotFoundState(state: NotFoundState | null) {
+  currentNotFoundState = state
+  notFoundListeners.forEach((listener) => listener())
+}
+
+export function clearNotFoundState() {
+  if (currentNotFoundState !== null) {
+    currentNotFoundState = null
+    notFoundListeners.forEach((listener) => listener())
+  }
+}
+
+// hook to subscribe to not-found state changes
+export function useNotFoundState(): NotFoundState | null {
+  const [, forceUpdate] = React.useReducer((x) => x + 1, 0)
+
+  React.useEffect(() => {
+    notFoundListeners.add(forceUpdate)
+    return () => {
+      notFoundListeners.delete(forceUpdate)
+    }
+  }, [])
+
+  return currentNotFoundState
+}
+
+// find nearest +not-found route by walking up the route tree from a path
+export function findNearestNotFoundRoute(
+  pathname: string,
+  rootNode: RouteNode | null
+): RouteNode | null {
+  if (!rootNode) return null
+
+  // normalize pathname
+  const pathParts = pathname.split('/').filter(Boolean)
+
+  // recursively search for +not-found at each level
+  function findNotFoundInNode(node: RouteNode): RouteNode | null {
+    // check if this node itself is a +not-found route
+    if (node.route === '+not-found') {
+      return node
+    }
+    // check children for +not-found
+    for (const child of node.children || []) {
+      if (child.route === '+not-found') {
+        return child
+      }
+    }
+    return null
+  }
+
+  // traverse tree to find route node matching path, collecting +not-found candidates
+  function traverse(
+    node: RouteNode,
+    depth: number,
+    notFoundStack: RouteNode[]
+  ): RouteNode | null {
+    // check for +not-found at this level
+    const notFoundAtLevel = findNotFoundInNode(node)
+    if (notFoundAtLevel) {
+      notFoundStack.push(notFoundAtLevel)
+    }
+
+    // if we've consumed all path parts, return the deepest +not-found found
+    if (depth >= pathParts.length) {
+      return notFoundStack.length > 0 ? notFoundStack[notFoundStack.length - 1] : null
+    }
+
+    const segment = pathParts[depth]
+
+    // find matching child
+    for (const child of node.children || []) {
+      // skip +not-found routes when matching
+      if (child.route === '+not-found') continue
+
+      // check for direct match or dynamic route
+      const childRoute = child.route || ''
+      const isDynamic = childRoute.startsWith('[')
+      const isMatch = childRoute === segment || isDynamic
+
+      if (isMatch) {
+        const result = traverse(child, depth + 1, [...notFoundStack])
+        if (result) return result
+      }
+    }
+
+    // no matching child, return deepest +not-found
+    return notFoundStack.length > 0 ? notFoundStack[notFoundStack.length - 1] : null
+  }
+
+  return traverse(rootNode, 0, [])
+}
+
+// find a route node by its path (e.g., "/ssg-not-found/+not-found")
+export function findRouteNodeByPath(
+  notFoundPath: string,
+  rootNode: RouteNode | null
+): RouteNode | null {
+  if (!rootNode) return null
+
+  // normalize path - remove leading slashes, ./, and trailing slashes
+  const normalizedPath = notFoundPath.replace(/^(\.?\/)+|\/+$/g, '')
+
+  // recursive search through all children
+  function searchNode(node: RouteNode): RouteNode | null {
+    // check if this node's contextKey matches (without extension and prefix)
+    const nodeContextKey = node.contextKey || ''
+    // strip leading ./ or /, and file extension
+    const contextKeyNormalized = nodeContextKey
+      .replace(/^(\.?\/)+/, '')
+      .replace(/\.[^.]+$/, '')
+
+    if (contextKeyNormalized === normalizedPath) {
+      return node
+    }
+
+    // check children
+    for (const child of node.children || []) {
+      const found = searchNode(child)
+      if (found) return found
+    }
+
+    return null
+  }
+
+  // search from root
+  const found = searchNode(rootNode)
+  if (found) return found
+
+  // also search root's children directly
+  for (const child of rootNode.children || []) {
+    const found = searchNode(child)
+    if (found) return found
+  }
+
+  return null
+}

package/src/router/router.ts

@@ -58,6 +58,11 @@ import {
   storeInterceptState,
 } from './interceptRoutes'
 import { setSlotState } from '../views/Navigator'
+import {
+  clearNotFoundState,
+  findNearestNotFoundRoute,
+  setNotFoundState,
+} from '../notFoundState'
 
 // Module-scoped variables
 export let routeNode: RouteNode | null = null
@@ -882,6 +887,9 @@ export async function linkTo(
   // This enables intercepting routes to activate
   setNavigationType('soft')
 
+  // clear any active not-found state on new navigation
+  clearNotFoundState()
+
   if (href[0] === '#') {
     // this is just linking to a section of the current page on web
     return
@@ -1026,7 +1034,13 @@ export async function linkTo(
     delete preloadedLoaderData[href]
     delete preloadingLoader[href]
     setLoadingState('loaded')
-    linkTo(preloadResult.__oneNotFoundPath || '/+not-found', 'REPLACE')
+    // render 404 inline at current URL instead of navigating
+    const notFoundRoute = findNearestNotFoundRoute(href, routeNode)
+    setNotFoundState({
+      notFoundPath: preloadResult.__oneNotFoundPath || '/+not-found',
+      notFoundRouteNode: notFoundRoute || undefined,
+      originalPath: href,
+    })
     return
   }
 

package/src/server/oneServe.ts

@@ -86,6 +86,15 @@ export async function oneServe(
     return '/+not-found'
   }
 
+  // generate a 404 loader response that triggers client-side not-found navigation
+  function make404LoaderJs(path: string, logReason?: string): string {
+    const nfPath = findNearestNotFoundPath(path)
+    if (logReason) {
+      console.error(`[one] 404 loader for ${path}: ${logReason}`)
+    }
+    return `export function loader(){return{__oneError:404,__oneErrorMessage:'Not Found',__oneNotFoundPath:${JSON.stringify(nfPath)}}}`
+  }
+
   const serverOptions = {
     ...oneOptions,
     root: '.',
@@ -165,7 +174,20 @@ export async function oneServe(
         return null
       }
 
-      const json = await loader(loaderProps)
+      let json
+      try {
+        json = await loader(loaderProps)
+      } catch (err) {
+        // for file-not-found errors (e.g., missing MDX for non-existent slug),
+        // return a 404 signal so the client navigates to +not-found
+        if ((err as any)?.code === 'ENOENT') {
+          return make404LoaderJs(
+            loaderProps?.path || '/',
+            `ENOENT ${(err as any)?.path || err}`
+          )
+        }
+        throw err
+      }
 
       // if the loader returned a Response (e.g. redirect()), throw it
       // so it bubbles up through resolveResponse and can be transformed
@@ -189,11 +211,6 @@ export async function oneServe(
         }
 
         try {
-          // Use lazy import if available (workers), otherwise dynamic import (Node.js)
-          const exported = options?.lazyRoutes?.pages?.[route.file]
-            ? await options.lazyRoutes.pages[route.file]()
-            : await import(toAbsolute(buildInfo.serverJsPath))
-
           // helper to import and run a single loader
           async function runLoader(
             routeId: string,
@@ -487,9 +504,17 @@ url: ${url}`)
             }
 
             if (notFoundHtml) {
+              // inject 404 marker so client knows this is a 404 response
+              // this prevents hydration mismatch when the URL matches a dynamic route
+              const notFoundMarker = `<script>window.__one404={originalPath:"${url.pathname}",notFoundPath:"${notFoundRoute}"}</script>`
+              // inject before </head> or at start of <body>
+              const injectedHtml = notFoundHtml.includes('</head>')
+                ? notFoundHtml.replace('</head>', `${notFoundMarker}</head>`)
+                : notFoundHtml.replace('<body', `${notFoundMarker}<body`)
+
               const headers = new Headers()
               headers.set('content-type', 'text/html')
-              return new Response(notFoundHtml, {
+              return new Response(injectedHtml, {
                 headers,
                 status: 404,
               })
@@ -551,10 +576,11 @@ url: ${url}`)
             // if not in routeMap, the slug wasn't in generateStaticParams - return 404
             if (route.type === 'ssg' && Object.keys(route.routeKeys).length > 0) {
               if (!routeMap[originalUrl]) {
-                const nfPath = findNearestNotFoundPath(originalUrl)
                 return new Response(
-                  `export function loader(){return{__oneError:404,__oneErrorMessage:'Not Found',__oneNotFoundPath:${JSON.stringify(nfPath)}}}`,
-                  { headers: { 'Content-Type': 'text/javascript' } }
+                  make404LoaderJs(originalUrl, 'ssg route not in routeMap'),
+                  {
+                    headers: { 'Content-Type': 'text/javascript' },
+                  }
                 )
               }
             }
@@ -710,12 +736,9 @@ url: ${url}`)
           Object.keys(route.routeKeys).length > 0 &&
           !routeMap[originalUrl]
         ) {
-          const nfPath = findNearestNotFoundPath(originalUrl)
           c.header('Content-Type', 'text/javascript')
           c.status(200)
-          return c.body(
-            `export function loader(){return{__oneError:404,__oneErrorMessage:'Not Found',__oneNotFoundPath:${JSON.stringify(nfPath)}}}`
-          )
+          return c.body(make404LoaderJs(originalUrl, 'ssg route not in routeMap'))
         }
 
         // for now just change this

package/src/useLoader.ts

@@ -1,8 +1,9 @@
 import { useCallback, useSyncExternalStore } from 'react'
 import { registerDevtoolsFunction } from './devtools/registry'
 import { useParams, usePathname } from './hooks'
+import { findNearestNotFoundRoute, setNotFoundState } from './notFoundState'
 import { router } from './router/imperative-api'
-import { preloadedLoaderData, preloadingLoader } from './router/router'
+import { preloadedLoaderData, preloadingLoader, routeNode } from './router/router'
 import { getLoaderPath } from './utils/cleanUrl'
 import { dynamicImport } from './utils/dynamicImport'
 import { weakKey } from './utils/weakKey'
@@ -165,7 +166,7 @@ export async function refetchLoader(pathname: string): Promise<void> {
     }
 
     // detect 404 error signal during refetch
-    // don't clear data - keep existing data while navigating to not-found
+    // render 404 inline at current URL instead of navigating
     if (result?.__oneError === 404) {
       recordLoaderTiming?.({
         path: pathname,
@@ -175,7 +176,12 @@ export async function refetchLoader(pathname: string): Promise<void> {
         totalTime,
         source: 'refetch',
       })
-      router.replace(result.__oneNotFoundPath || '/+not-found')
+      const notFoundRoute = findNearestNotFoundRoute(pathname, routeNode)
+      setNotFoundState({
+        notFoundPath: result.__oneNotFoundPath || '/+not-found',
+        notFoundRouteNode: notFoundRoute || undefined,
+        originalPath: pathname,
+      })
       return
     }
 
@@ -394,7 +400,7 @@ export function useLoaderState<
               }
 
               // detect 404 error signal on native
-              // don't update state so the component stays suspended while navigating
+              // render 404 inline at current URL instead of navigating
               if (data?.__oneError === 404) {
                 recordLoaderTiming?.({
                   path: currentPath,
@@ -404,9 +410,13 @@ export function useLoaderState<
                   totalTime,
                   source: 'initial',
                 })
-                router.replace(data.__oneNotFoundPath || '/+not-found')
-                // keep component suspended until navigation unmounts it
-                await new Promise(() => {})
+                const notFoundRoute = findNearestNotFoundRoute(currentPath, routeNode)
+                setNotFoundState({
+                  notFoundPath: data.__oneNotFoundPath || '/+not-found',
+                  notFoundRouteNode: notFoundRoute || undefined,
+                  originalPath: currentPath,
+                })
+                return
               }
 
               updateState(currentPath, {
@@ -483,8 +493,7 @@ export function useLoaderState<
             return
           }
 
-          // detect 404 error signal - navigate to not-found page
-          // don't update state so the component stays suspended while navigating
+          // detect 404 error signal - render 404 inline at current URL
           if (result?.__oneError === 404) {
             recordLoaderTiming?.({
               path: currentPath,
@@ -494,9 +503,13 @@ export function useLoaderState<
               totalTime,
               source: 'initial',
             })
-            router.replace(result.__oneNotFoundPath || '/+not-found')
-            // keep component suspended until navigation unmounts it
-            await new Promise(() => {})
+            const notFoundRoute = findNearestNotFoundRoute(currentPath, routeNode)
+            setNotFoundState({
+              notFoundPath: result.__oneNotFoundPath || '/+not-found',
+              notFoundRouteNode: notFoundRoute || undefined,
+              originalPath: currentPath,
+            })
+            return
           }
 
           updateState(currentPath, {

package/src/utils/cleanUrl.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import { getLoaderPath, getPathFromLoaderPath } from './cleanUrl'
+
+/**
+ * tests the cleanUrl encode/decode roundtrip used for loader URLs.
+ *
+ * cleanUrl encodes a URL path into a flat filename segment:
+ *   - escapes underscores: _ → __
+ *   - replaces slashes: / → _
+ *
+ * getPathFromLoaderPath reverses it:
+ *   - __ → _ (escaped underscore)
+ *   - _  → / (path separator)
+ */
+
+function roundtrip(path: string): string {
+  const loaderPath = getLoaderPath(path, false)
+  return getPathFromLoaderPath(loaderPath)
+}
+
+describe('cleanUrl roundtrip', () => {
+  it('simple path', () => {
+    expect(roundtrip('/docs/getting-started')).toBe('/docs/getting-started')
+  })
+
+  it('path with underscore prefix (/_/docs)', () => {
+    expect(roundtrip('/_/docs/getting-started')).toBe('/_/docs/getting-started')
+  })
+
+  it('path with underscore prefix (/_/terms)', () => {
+    expect(roundtrip('/_/terms')).toBe('/_/terms')
+  })
+
+  it('path with underscore in segment name', () => {
+    expect(roundtrip('/my_page/test')).toBe('/my_page/test')
+  })
+
+  it('deeply nested path', () => {
+    expect(roundtrip('/deep/nested/path/here')).toBe('/deep/nested/path/here')
+  })
+
+  it('root path', () => {
+    expect(roundtrip('/')).toBe('/')
+  })
+
+  it('single segment', () => {
+    expect(roundtrip('/about')).toBe('/about')
+  })
+
+  it('path with query string is stripped', () => {
+    const loaderPath = getLoaderPath('/docs/intro?foo=bar', false)
+    expect(getPathFromLoaderPath(loaderPath)).toBe('/docs/intro')
+  })
+
+  it('path with hash is stripped', () => {
+    const loaderPath = getLoaderPath('/docs/intro#section', false)
+    expect(getPathFromLoaderPath(loaderPath)).toBe('/docs/intro')
+  })
+
+  it('path with trailing slash', () => {
+    const loaderPath = getLoaderPath('/docs/intro/', false)
+    expect(getPathFromLoaderPath(loaderPath)).toBe('/docs/intro')
+  })
+})
+
+describe('getLoaderPath format', () => {
+  it('includes /assets/ prefix', () => {
+    const result = getLoaderPath('/docs/intro', false)
+    expect(result).toMatch(/^\/assets\//)
+  })
+
+  it('ends with loader postfix', () => {
+    const result = getLoaderPath('/docs/intro', false)
+    expect(result).toMatch(/_\d+_vxrn_loader\.js$/)
+  })
+
+  it('includes /_one prefix in dev mode', () => {
+    const originalEnv = process.env.NODE_ENV
+    process.env.NODE_ENV = 'development'
+    try {
+      const result = getLoaderPath('/docs/intro', false)
+      expect(result).toMatch(/^\/_one\/assets\//)
+    } finally {
+      process.env.NODE_ENV = originalEnv
+    }
+  })
+
+  it('includes cache bust segment', () => {
+    const result = getLoaderPath('/docs/intro', false, '12345')
+    expect(result).toContain('_refetch_12345_')
+  })
+})
+
+describe('getPathFromLoaderPath', () => {
+  it('strips /_one/assets prefix', () => {
+    expect(getPathFromLoaderPath('/_one/assets/docs_intro_999_vxrn_loader.js')).toBe(
+      '/docs/intro'
+    )
+  })
+
+  it('strips /assets prefix', () => {
+    expect(getPathFromLoaderPath('/assets/docs_intro_999_vxrn_loader.js')).toBe(
+      '/docs/intro'
+    )
+  })
+
+  it('strips refetch cache bust', () => {
+    expect(
+      getPathFromLoaderPath('/assets/docs_intro_refetch_12345__999_vxrn_loader.js')
+    ).toBe('/docs/intro')
+  })
+
+  it('decodes escaped underscores back to literal underscores', () => {
+    // path /_/docs/intro → cleanUrl("_/docs/intro") → "___docs_intro"
+    // ___ decodes as: __ → "_", _ → "/" → "/_/docs/intro"
+    expect(getPathFromLoaderPath('/assets/___docs_intro_999_vxrn_loader.js')).toBe(
+      '/_/docs/intro'
+    )
+  })
+})

package/src/utils/cleanUrl.ts

@@ -9,12 +9,10 @@ import { getURL } from '../getURL'
 import { removeSearch } from './removeSearch'
 
 function cleanUrl(path: string) {
-  return (
-    removeSearch(path)
-      .replaceAll('/', '_')
-      // remove trailing _
-      .replace(/_$/, '')
-  )
+  return removeSearch(path)
+    .replace(/\/$/, '') // remove trailing slash before encoding
+    .replaceAll('_', '__') // escape existing underscores
+    .replaceAll('/', '_') // use underscore as path separator
 }
 
 const isClient = typeof window !== 'undefined'
@@ -45,9 +43,12 @@ export function getLoaderPath(
 }
 
 export function getPathFromLoaderPath(loaderPath: string) {
-  return loaderPath
-    .replace(LOADER_JS_POSTFIX_REGEX, '')
-    .replace(/^(\/_one)?\/assets/, '')
-    .replace(/_refetch_\d+_/, '')
-    .replaceAll(/_/g, '/')
+  return (
+    loaderPath
+      .replace(LOADER_JS_POSTFIX_REGEX, '')
+      .replace(/^(\/_one)?\/assets/, '')
+      .replace(/_refetch_\d+_/, '')
+      // decode: __ → _ (escaped underscore), _ → / (path separator)
+      .replace(/__|_/g, (match) => (match === '__' ? '_' : '/'))
+  )
 }