one 1.21.1 → 1.21.3

package/src/router/hmrImport.native.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { hmrImport } from './hmrImport.native'
+
+const realRuntime = (globalThis as any).__rolldown_runtime__
+afterEach(() => {
+  ;(globalThis as any).__rolldown_runtime__ = realRuntime
+  vi.restoreAllMocks()
+})
+const setRuntime = (runtime: unknown) => {
+  ;(globalThis as any).__rolldown_runtime__ = runtime
+}
+
+describe('hmrImport (native)', () => {
+  it('rejects when no runtime is present', async () => {
+    setRuntime(undefined)
+    await expect(hmrImport('foo.tsx')).rejects.toThrow(
+      'HMR import not supported on native'
+    )
+  })
+
+  it('rejects when loadExports is missing', async () => {
+    setRuntime({})
+    await expect(hmrImport('foo.tsx')).rejects.toThrow(
+      'HMR import not supported on native'
+    )
+  })
+
+  it('resolves with the runtime exports and strips ./ and / prefixes', async () => {
+    const exports = { default: () => null }
+    const loadExports = vi.fn(() => exports)
+    setRuntime({ loadExports })
+
+    await expect(hmrImport('./foo.tsx')).resolves.toBe(exports)
+    await expect(hmrImport('/foo.tsx')).resolves.toBe(exports)
+    await expect(hmrImport('foo.tsx')).resolves.toBe(exports)
+    expect(loadExports).toHaveBeenNthCalledWith(1, 'foo.tsx')
+    expect(loadExports).toHaveBeenNthCalledWith(2, 'foo.tsx')
+    expect(loadExports).toHaveBeenNthCalledWith(3, 'foo.tsx')
+  })
+
+  it('rejects when loadExports returns null', async () => {
+    setRuntime({ loadExports: () => null })
+    await expect(hmrImport('foo.tsx')).rejects.toThrow('no exports for foo.tsx')
+  })
+
+  it('rejects when loadExports throws', async () => {
+    const boom = new Error('boom')
+    setRuntime({
+      loadExports: () => {
+        throw boom
+      },
+    })
+    await expect(hmrImport('foo.tsx')).rejects.toBe(boom)
+  })
+})

package/src/router/hmrImport.native.ts

@@ -1,8 +1,28 @@
 /**
- * Native stub: HMR cache-busting is not supported on native.
- * This avoids the dynamic import() syntax that Hermes cannot parse.
+ * native HMR re-import
+ *
+ * vxrn's native dev runtime re-registers the edited module into
+ * `globalThis.__rolldown_runtime__` before One evicts its route cache, so the
+ * fresh exports can be pulled straight from the runtime without dynamic `import()`
+ * (which Hermes cannot parse). Rejects when the runtime is unavailable so a
+ * broken development runtime is visible instead of serving a stale route.
  */
-export function hmrImport(_path: string): Promise<any> {
-  // Return a rejected promise to fall back to normal import
-  return Promise.reject(new Error('HMR import not supported on native'))
+export function hmrImport(path: string): Promise<any> {
+  const runtime = (
+    globalThis as typeof globalThis & {
+      __rolldown_runtime__?: { loadExports(id: string): unknown }
+    }
+  ).__rolldown_runtime__
+  if (!runtime || typeof runtime.loadExports !== 'function') {
+    return Promise.reject(new Error('HMR import not supported on native'))
+  }
+  // route paths arrive as `./foo.tsx` / `/foo.tsx`; rolldown ids are bare (`foo.tsx`)
+  const id = path.replace(/^\.\//, '').replace(/^\//, '')
+  return Promise.resolve().then(() => {
+    const mod = runtime.loadExports(id)
+    if (mod == null) {
+      throw new Error(`no exports for ${id}`)
+    }
+    return mod
+  })
 }

package/src/router/matchers.ts

@@ -169,6 +169,16 @@ export interface DirectoryRenderModeMatch {
   renderMode: One.RouteRenderMode | 'api'
 }
 
+/** match file render mode suffixes: index+ssr.tsx, feed+spa.web.tsx, etc. */
+export function matchFileRenderMode(
+  name: string
+): One.RouteRenderMode | 'api' | undefined {
+  const mode = name.match(/\+(api|ssg|ssr|spa)\.(?:\w+\.)?[jt]sx?$/)?.[1]
+  if (mode === 'api' || mode === 'ssg' || mode === 'ssr' || mode === 'spa') {
+    return mode
+  }
+}
+
 /**
  * Match directory render mode suffixes
  *

package/src/router/routeHmr.native.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+type RouteHmrModule = typeof import('./routeHmr.native')
+
+describe('routeHmr.native', () => {
+  let routeHmr: RouteHmrModule
+  const realWindow = (globalThis as any).window
+  const realModuleUpdatedHook = globalThis.__VXRN_ON_MODULE_UPDATED__
+
+  beforeEach(async () => {
+    // the __VXRN_ON_MODULE_UPDATED__ registration is dev-gated and runs at module
+    // load, so stub NODE_ENV then re-import to exercise it
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.resetModules()
+    routeHmr = await import('./routeHmr.native')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    globalThis.__VXRN_ON_MODULE_UPDATED__ = realModuleUpdatedHook
+    ;(globalThis as any).window = realWindow
+  })
+
+  it('registers globalThis.__VXRN_ON_MODULE_UPDATED__ in development', () => {
+    expect(typeof globalThis.__VXRN_ON_MODULE_UPDATED__).toBe('function')
+  })
+
+  it('bumps the epoch and notifies subscribers, and stops after unsubscribe', () => {
+    const before = routeHmr.getRouteHmrEpoch()
+    const listener = vi.fn()
+    const unsubscribe = routeHmr.subscribeRouteHmr(listener)
+
+    globalThis.__VXRN_ON_MODULE_UPDATED__!('app/index.tsx')
+    expect(routeHmr.getRouteHmrEpoch()).toBe(before + 1)
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    unsubscribe()
+    globalThis.__VXRN_ON_MODULE_UPDATED__!('app/index.tsx')
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('evicts the route cache for the updated file when window.__oneRouteCache is present', () => {
+    const clearFile = vi.fn()
+    ;(globalThis as any).window = { __oneRouteCache: { clearFile } }
+    globalThis.__VXRN_ON_MODULE_UPDATED__!('app/_layout.tsx')
+    expect(clearFile).toHaveBeenCalledWith('app/_layout.tsx')
+  })
+
+  it('does not throw when window / route cache is absent', () => {
+    ;(globalThis as any).window = undefined
+    expect(() => globalThis.__VXRN_ON_MODULE_UPDATED__!('x.tsx')).not.toThrow()
+  })
+
+  it('still notifies subscribers when route-cache eviction throws', () => {
+    const listener = vi.fn()
+    const unsubscribe = routeHmr.subscribeRouteHmr(listener)
+    ;(globalThis as any).window = {
+      __oneRouteCache: {
+        clearFile() {
+          throw new Error('cache eviction failed')
+        },
+      },
+    }
+
+    expect(() => globalThis.__VXRN_ON_MODULE_UPDATED__!('app/index.tsx')).toThrow(
+      'cache eviction failed'
+    )
+    expect(listener).toHaveBeenCalledOnce()
+    unsubscribe()
+  })
+})

package/src/router/routeHmr.native.ts

@@ -0,0 +1,37 @@
+// native Fast Refresh for One routes
+//
+// vxrn calls the global hook after committing an updated module. One evicts that
+// route and bumps this external-store epoch so mounted screens load fresh exports.
+
+declare global {
+  // vxrn's native HMR runtime invokes this (when defined) with each committed
+  // module id, so a framework can react to a hot update.
+  var __VXRN_ON_MODULE_UPDATED__: ((moduleId: string) => void) | undefined
+}
+
+let routeHmrEpoch = 0
+const routeHmrListeners = new Set<() => void>()
+
+export const subscribeRouteHmr = (onStoreChange: () => void) => {
+  routeHmrListeners.add(onStoreChange)
+  return () => {
+    routeHmrListeners.delete(onStoreChange)
+  }
+}
+
+export const getRouteHmrEpoch = () => routeHmrEpoch
+
+if (process.env.NODE_ENV === 'development') {
+  globalThis.__VXRN_ON_MODULE_UPDATED__ = (id: string) => {
+    try {
+      const routeCache =
+        typeof window === 'undefined' ? undefined : (window as any).__oneRouteCache
+      if (typeof routeCache?.clearFile === 'function') {
+        routeCache.clearFile(id)
+      }
+    } finally {
+      routeHmrEpoch++
+      routeHmrListeners.forEach((listener) => listener())
+    }
+  }
+}

package/src/router/routeHmr.ts

@@ -0,0 +1,8 @@
+// web counterpart of routeHmr.native.ts. Web route Fast Refresh happens through
+// the `one-hmr-update` event (see useScreens' web block), so this is a no-op store
+// whose exports let useScreens import `./routeHmr` on either platform.
+export const subscribeRouteHmr = (_onStoreChange: () => void): (() => void) => {
+  return () => {}
+}
+
+export const getRouteHmrEpoch = () => 0

package/src/router/useScreens.tsx

@@ -28,6 +28,7 @@ import {
 import { SpaShellContext } from './SpaShellContext'
 import { NamedSlot } from '../views/Navigator'
 import { sortRoutesWithInitial } from './sortRoutes'
+import { getRouteHmrEpoch, subscribeRouteHmr } from './routeHmr'
 import { getClientMatchesSnapshot } from '../useMatches'
 
 // `@react-navigation/core` does not expose the Screen or Group components directly, so we have to
@@ -395,6 +396,17 @@ export function getQualifiedRouteComponent(value: RouteNode) {
       }, [])
     }
 
+    // native Fast Refresh: subscribe to the route-hot epoch (the routeHmr.native
+    // store bumps it when vxrn reports a route module update) so this component
+    // re-renders and re-runs loadRoute() to pick up the edited module's exports
+    if (
+      process.env.NODE_ENV === 'development' &&
+      process.env.TAMAGUI_TARGET === 'native'
+    ) {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      React.useSyncExternalStore(subscribeRouteHmr, getRouteHmrEpoch, getRouteHmrEpoch)
+    }
+
     // in spa-shell mode, only SSG/SSR layouts render on the server.
     // SPA layouts and leaf pages get a placeholder, swapped for real
     // content after hydration.

package/src/router/useViteRoutes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  hmrImport: vi.fn(),
+}))
+
+vi.mock('./hmrImport', () => ({
+  hmrImport: mocks.hmrImport,
+}))
+
+import { globbedRoutesToRouteContext } from './useViteRoutes'
+
+const realWindow = (globalThis as any).window
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  mocks.hmrImport.mockReset()
+  ;(globalThis as any).window = realWindow
+})
+
+async function resolveRoute(context: ReturnType<typeof globbedRoutesToRouteContext>) {
+  try {
+    return context('./index.tsx')
+  } catch (pending) {
+    await pending
+    return context('./index.tsx')
+  }
+}
+
+describe('globbedRoutesToRouteContext HMR', () => {
+  it('evicts and reloads a route under a custom router root', async () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    ;(globalThis as any).window = {}
+    const initialRoute = { default: () => 'initial' }
+    const updatedRoute = { default: () => 'updated' }
+    const context = globbedRoutesToRouteContext(
+      { '/routes/index.tsx': () => Promise.resolve(initialRoute) },
+      'routes'
+    )
+
+    await expect(resolveRoute(context)).resolves.toBe(initialRoute)
+
+    mocks.hmrImport.mockResolvedValue(updatedRoute)
+    ;(globalThis as any).window.__oneRouteCache.clearFile('routes/index.tsx')
+
+    await expect(resolveRoute(context)).resolves.toBe(updatedRoute)
+    expect(mocks.hmrImport).toHaveBeenCalledWith('/routes/index.tsx')
+  })
+})

package/src/router/useViteRoutes.tsx

@@ -221,24 +221,16 @@ export function globbedRoutesToRouteContext(
       },
       clearFile: (file: string) => {
         hmrVersion++
-        // Clear only the specific file's cache
-        // file is like "app/_layout.tsx", need to match against keys like "./_layout.tsx"
-        const normalizedFile = file.replace(/^app\//, './')
-        Object.keys(loadedRoutes).forEach((key) => {
-          if (key === normalizedFile || key.endsWith(normalizedFile.replace('./', '/'))) {
-            delete loadedRoutes[key]
-          }
-        })
-        Object.keys(promises).forEach((key) => {
-          if (key === normalizedFile || key.endsWith(normalizedFile.replace('./', '/'))) {
-            delete promises[key]
-          }
-        })
-        Object.keys(preloadedModules).forEach((key) => {
-          if (key.includes(file)) {
-            delete preloadedModules[key]
-          }
-        })
+        const normalizedFile = file.replace(/\\/g, '/').replace(/^\//, '')
+        const routeId = moduleKeys.find(
+          (key) =>
+            routePaths[key].replace(/\\/g, '/').replace(/^\//, '') === normalizedFile
+        )
+        if (!routeId) return
+
+        delete loadedRoutes[routeId]
+        delete promises[routeId]
+        delete preloadedModules[routePaths[routeId]]
       },
       getVersion: () => hmrVersion,
     }
@@ -264,11 +256,10 @@ export function globbedRoutesToRouteContext(
     }
 
     if (!promises[id]) {
-      // In dev mode after HMR, use cache-busting import to get fresh module
-      // hmrImport is platform-specific: .native.ts returns rejected promise, base uses dynamic import()
+      // in dev mode after HMR, load the fresh module through the platform runtime
       let importPromise: Promise<any>
       if (process.env.NODE_ENV === 'development' && hmrVersion > 0 && routePaths[id]) {
-        importPromise = hmrImport(routePaths[id]).catch(() => routesSync[id]())
+        importPromise = hmrImport(routePaths[id])
       } else {
         importPromise = routesSync[id]()
       }

package/src/utils/cleanUrl.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from 'vitest'
-import { getLoaderPath, getPathFromLoaderPath } from './cleanUrl'
+import {
+  encodeReservedFilenameChars,
+  getLoaderPath,
+  getPathFromLoaderPath,
+  getPreloadPath,
+} from './cleanUrl'
 
 /**
  * tests the cleanUrl encode/decode roundtrip used for loader URLs.
@@ -91,6 +96,63 @@ describe('getLoaderPath format', () => {
   })
 })
 
+describe('NTFS-reserved characters in route-derived names', () => {
+  // route patterns reach these functions verbatim when a dynamic route has no
+  // generateStaticParams (every dynamic +ssr/+spa route at build time)
+  it('roundtrips a root dynamic route pattern', () => {
+    expect(roundtrip('/:param')).toBe('/:param')
+  })
+
+  it('roundtrips a nested dynamic route pattern', () => {
+    expect(roundtrip('/dashboard/:appId')).toBe('/dashboard/:appId')
+  })
+
+  it('roundtrips a catch-all pattern', () => {
+    expect(roundtrip('/*')).toBe('/*')
+  })
+
+  it('roundtrips hostile concrete param values (chars that survive URL parsing raw)', () => {
+    // getLoaderPath URL-parses its input; WHATWG URL percent-encodes " < > |
+    // in pathnames but passes : and * through raw — those two are the ones
+    // that reach generated filenames verbatim (and are the NTFS killers)
+    expect(roundtrip('/blog/a:b*c')).toBe('/blog/a:b*c')
+  })
+
+  it('emits filesystem-legal names for the full reserved set via preload paths', () => {
+    // getPreloadPath does not URL-parse, so every reserved char reaches the
+    // encoder raw — assert none survive into the filename
+    expect(getPreloadPath('/blog/a:b*c"d<e>f|g?h')).not.toMatch(/[<>:"|?*]/)
+  })
+
+  it('roundtrips literal equals signs (self-escape)', () => {
+    expect(roundtrip('/foo=bar')).toBe('/foo=bar')
+  })
+
+  it('roundtrips equals followed by hex-looking characters', () => {
+    expect(roundtrip('/x=3ay')).toBe('/x=3ay')
+  })
+
+  it('emits no NTFS-reserved characters in loader filenames', () => {
+    expect(getLoaderPath('/dashboard/:appId', false)).not.toMatch(/[<>:"|?*]/)
+  })
+
+  it('emits no NTFS-reserved characters in preload filenames', () => {
+    expect(getPreloadPath('/:param')).not.toMatch(/[<>:"|?*]/)
+    expect(getPreloadPath('/*')).not.toMatch(/[<>:"|?*]/)
+  })
+
+  it('encodeReservedFilenameChars is identity for clean paths', () => {
+    expect(encodeReservedFilenameChars('/blog/my-slug.html')).toBe('/blog/my-slug.html')
+  })
+
+  it('encodes the html artifact path for non-prerendered dynamic routes', () => {
+    expect(encodeReservedFilenameChars('/dashboard/:appId.html')).toBe(
+      '/dashboard/=3aappId.html'
+    )
+    expect(encodeReservedFilenameChars('/*.html')).toBe('/=2a.html')
+  })
+})
+
 describe('getPathFromLoaderPath', () => {
   it('strips /_one/assets prefix', () => {
     expect(getPathFromLoaderPath('/_one/assets/docs_intro_999_vxrn_loader.js')).toBe(

package/src/utils/cleanUrl.ts

@@ -8,9 +8,31 @@ import {
 import { getURL } from '../getURL'
 import { removeSearch } from './removeSearch'
 
+// Route patterns (`/:param`, `/*`) and concrete param values flow into
+// generated artifact filenames. `< > : " | ? *` are reserved on Windows
+// filesystems — a leading `:` segment fails outright and a mid-name `:`
+// silently writes an NTFS alternate data stream — so encode them as `=hh`
+// (hex char code), with literal `=` self-escaped first so decoding is
+// unambiguous. Identity for paths without reserved characters.
+export function encodeReservedFilenameChars(path: string) {
+  return path
+    .replaceAll('=', '=3d')
+    .replace(
+      /[<>:"|?*]/g,
+      (char) => `=${char.charCodeAt(0).toString(16).padStart(2, '0')}`
+    )
+}
+
+export function decodeReservedFilenameChars(path: string) {
+  return path.replace(/=([0-9a-f]{2})/g, (_match, hexCode) =>
+    String.fromCharCode(Number.parseInt(hexCode, 16))
+  )
+}
+
 function cleanUrl(path: string) {
-  return removeSearch(path)
-    .replace(/\/$/, '') // remove trailing slash before encoding
+  return encodeReservedFilenameChars(
+    removeSearch(path).replace(/\/$/, '') // remove trailing slash before encoding
+  )
     .replaceAll('_', '__') // escape existing underscores
     .replaceAll('/', '_') // use underscore as path separator
 }
@@ -43,7 +65,7 @@ export function getLoaderPath(
 }
 
 export function getPathFromLoaderPath(loaderPath: string) {
-  return (
+  return decodeReservedFilenameChars(
     loaderPath
       .replace(LOADER_JS_POSTFIX_REGEX, '')
       .replace(/^(\/_one)?\/assets/, '')

package/src/vite/plugins/virtualEntryPlugin.test.ts

@@ -1,4 +1,9 @@
+import { Buffer } from 'node:buffer'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
+import { build } from 'vite'
 import { createVirtualEntry } from './virtualEntryPlugin'
 
 // mock isNativeEnvironment
@@ -22,6 +27,71 @@ function loadEntry(plugin: any, envName: string, command: 'serve' | 'build' = 'b
 }
 
 describe('virtualEntryPlugin', () => {
+  it('keeps spa route matching without bundling the client module on the server', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'one-spa-server-'))
+    const appDir = join(root, 'app')
+    mkdirSync(appDir)
+    const spaRoute = join(appDir, 'client-only+spa.tsx')
+    writeFileSync(
+      spaRoute,
+      `export const browserPayload = 'must-not-enter-server-graph'
+export default function ClientOnlyPage() { return null }
+`
+    )
+
+    try {
+      const result = await build({
+        root,
+        configFile: false,
+        logLevel: 'silent',
+        plugins: [
+          {
+            name: 'test-one-entry',
+            enforce: 'pre',
+            resolveId(id) {
+              if (id === 'one') return '\0test-one-entry'
+            },
+            load(id) {
+              if (id === '\0test-one-entry') {
+                return `export const createApp = (options) => options
+export const registerPreloadedRoute = () => {}`
+              }
+            },
+          },
+          createVirtualEntry({ root: 'app', flags: {} }),
+        ],
+        build: {
+          ssr: true,
+          write: false,
+          rolldownOptions: {
+            input: 'virtual:one-entry',
+          },
+        },
+      })
+      if (Array.isArray(result)) throw new Error('expected one server build output')
+      if (!('output' in result)) throw new Error('expected completed server build')
+
+      const moduleIds = result.output.flatMap((output) =>
+        output.type === 'chunk' ? output.moduleIds : []
+      )
+      expect(moduleIds).not.toContain(resolve(spaRoute))
+
+      const entry = result.output.find(
+        (output) => output.type === 'chunk' && output.isEntry
+      )
+      if (!entry || entry.type !== 'chunk') throw new Error('missing server entry chunk')
+      const built = await import(
+        `data:text/javascript;base64,${Buffer.from(entry.code).toString('base64')}`
+      )
+      expect(Object.keys(built.default.routes)).toContain('/app/client-only+spa.tsx')
+      await expect(built.default.routes['/app/client-only+spa.tsx']()).resolves.toEqual(
+        {}
+      )
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
   describe('setupFile', () => {
     const base = {
       root: 'app',

package/src/vite/plugins/virtualEntryPlugin.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { configuration } from '@vxrn/compiler'
+import Glob from 'fast-glob'
 import type { Plugin } from 'vite'
 import { isNativeEnvironment } from 'vxrn'
 import {
@@ -9,6 +10,7 @@ import {
   ROUTE_NATIVE_EXCLUSION_GLOB_PATTERNS,
   ROUTE_WEB_EXCLUSION_GLOB_PATTERNS,
 } from '../../router/glob-patterns'
+import { matchDirectoryRenderMode, matchFileRenderMode } from '../../router/matchers'
 import type { One } from '../types'
 import {
   resolvedVirtualEntryId,
@@ -151,6 +153,47 @@ export function createVirtualEntry(options: {
       if (id === resolvedVirtualEntryId) {
         const isNative = isNativeEnvironment(this.environment)
         const isSSR = this.environment.name === 'ssr'
+        const serverSpaRouteFiles = isSSR
+          ? Glob.sync('**/*.{ts,tsx}', {
+              cwd: resolve(viteRoot, options.root),
+              ignore: [
+                ...ROUTE_WEB_EXCLUSION_GLOB_PATTERNS,
+                ...(options.router?.ignoredRouteFiles || []),
+              ],
+            })
+              .map((file) => file.replaceAll('\\', '/'))
+              .filter((file) => {
+                const parts = file.split('/')
+                const filename = parts.at(-1) || ''
+                if (
+                  filename.startsWith('_layout') ||
+                  filename.startsWith('_middleware')
+                ) {
+                  return false
+                }
+
+                const fileMode = matchFileRenderMode(filename)
+                if (fileMode) return fileMode === 'spa'
+
+                let parentMode: One.RouteRenderMode | 'api' | undefined
+                for (const directory of parts.slice(0, -1)) {
+                  parentMode =
+                    matchDirectoryRenderMode(directory)?.renderMode ?? parentMode
+                }
+                return parentMode === 'spa'
+              })
+          : []
+        const serverSpaRouteStubs = serverSpaRouteFiles
+          .map(
+            (file) =>
+              `${JSON.stringify(`/${options.root}/${file}`)}: () => Promise.resolve({})`
+          )
+          .join(',\n    ')
+        const webRouteGlobs = [
+          ...routeGlobs,
+          ...ROUTE_WEB_EXCLUSION_GLOB_PATTERNS.map((pattern) => `!${pattern}`),
+          ...serverSpaRouteFiles.map((file) => `!/${options.root}/${file}`),
+        ]
         // native always needs static import. SSR in dev mode uses static import
         // so Vite crawls the setupFile's dep tree (including react) and pre-bundles
         // them before the first request. SSR in build mode uses lazy import so the
@@ -191,10 +234,13 @@ if (typeof window !== 'undefined') {
   window.__oneRegisterPreloadedRoute = registerPreloadedRoute
 }
 
-// globbing ${JSON.stringify(routeGlobs)}
+// globbing ${JSON.stringify(webRouteGlobs)}
 export default createApp({
   ${setupPromiseArg}
-  routes: import.meta.glob(${JSON.stringify([...routeGlobs, ...ROUTE_WEB_EXCLUSION_GLOB_PATTERNS.map((p) => `!${p}`)])}, { exhaustive: true }),
+  routes: {
+    ...import.meta.glob(${JSON.stringify(webRouteGlobs)}, { exhaustive: true }),
+    ${serverSpaRouteStubs}
+  },
   routerRoot: ${JSON.stringify(options.root)},
   flags: ${JSON.stringify(options.flags)},
   ${linkingArg}

package/src/vite/types.ts

@@ -599,6 +599,15 @@ export namespace One {
       server?: VXRNBuildOptions | false
       api?: VXRNBuildOptions
 
+      /**
+       * maximum number of static pages to build concurrently.
+       * lower this when builds share a machine with other CPU-heavy work.
+       * `ONE_BUILD_CONCURRENCY` overrides this value.
+       *
+       * @default Math.min(available CPU cores, 8)
+       */
+      concurrency?: number
+
       /**
        * Use worker threads for parallel static page generation during build.
        * This utilizes multiple CPU cores for faster builds.

package/types/cli/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AA0XA,wBAAsB,KAAK,CAAC,IAAI,EAAE;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAA;IACpC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,iBA8vCA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAmXA,wBAAsB,KAAK,CAAC,IAAI,EAAE;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAA;IACpC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,iBA4wCA"}

package/types/cli/buildPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildPage.d.ts","sourceRoot":"","sources":["../../src/cli/buildPage.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAkBnD,wBAAgB,iBAAiB,SAUhC;AAED,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,GAAG,EACX,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,EAC7B,mBAAmB,EAAE,GAAG,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,MAAM,EAAE,EACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,cAAc,CAAC,EAAE,MAAM,EAAE,EACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAC3B,WAAW,CAAC,EAAE,OAAO,EACrB,qBAAqB,CAAC,EAAE,OAAO,GAC9B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAka7B"}
+{"version":3,"file":"buildPage.d.ts","sourceRoot":"","sources":["../../src/cli/buildPage.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAkBnD,wBAAgB,iBAAiB,SAUhC;AAED,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,GAAG,EACX,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,EAC7B,mBAAmB,EAAE,GAAG,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,MAAM,EAAE,EACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,cAAc,CAAC,EAAE,MAAM,EAAE,EACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAC3B,WAAW,CAAC,EAAE,OAAO,EACrB,qBAAqB,CAAC,EAAE,OAAO,GAC9B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAua7B"}