one 1.17.9 → 1.17.10

package/src/serve.ts

@@ -6,6 +6,7 @@ import type { VXRNOptions } from 'vxrn'
 import { setServerGlobals } from './server/setServerGlobals'
 import { setupBuildInfo } from './server/setupBuildOptions'
 import { ensureExists } from './utils/ensureExists'
+import { resolveServeOutDir } from './utils/buildOutputPointer'
 import type { One } from './vite/types'
 
 // formatErrorSafely + the prepareStackTrace guard prevent a buggy transitive
@@ -191,8 +192,7 @@ async function serveWithCluster(args: Parameters<typeof serve>[0], numWorkers: n
 }
 
 async function startWorker(args: Parameters<typeof serve>[0]) {
-  const outDir =
-    args?.outDir || (FSExtra.existsSync('buildInfo.json') ? '.' : null) || 'dist'
+  const outDir = await resolveServeOutDir(args?.outDir)
   const buildInfo = (await FSExtra.readJSON(`${outDir}/buildInfo.json`)) as One.BuildInfo
   const { oneOptions } = buildInfo
 

package/src/server/ServerContextScript.tsx

@@ -25,12 +25,18 @@ export function ServerContextScript() {
     // strip cssContents - read from DOM instead (CSSPrehydrateScript)
     const { cssContents, ...restContext } = context || {}
 
-    // strip page loaderData from matches to avoid double-serialization
-    const compactMatches = restContext.matches?.map((m: any) => ({
+    // strip page loaderData from matches to avoid double-serialization.
+    // we always strip the leaf (its data lives in restContext.loaderData and
+    // gets restored client-side onto matches[last]). reference equality on
+    // restContext.loaderData was too aggressive — if a layout's loaderData
+    // happened to ref-equal the page's (e.g. both `null`), the layout would
+    // permanently lose its data after hydration.
+    const lastMatchIndex = (restContext.matches?.length ?? 0) - 1
+    const compactMatches = restContext.matches?.map((m: any, i: number) => ({
       routeId: m.routeId,
       pathname: m.pathname,
       params: m.params,
-      ...(m.loaderData !== restContext.loaderData ? { loaderData: m.loaderData } : {}),
+      ...(i === lastMatchIndex ? {} : { loaderData: m.loaderData }),
     }))
 
     const clientContext = {

package/src/server/oneServe.ts

@@ -1,11 +1,11 @@
 import type { Hono, MiddlewareHandler } from 'hono'
 import type { BlankEnv } from 'hono/types'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, posix } from 'node:path'
 import {
-  CSS_PRELOAD_JS_POSTFIX,
+  CSS_PRELOAD_JS_POSTFIX_REGEX,
   LOADER_JS_POSTFIX_UNCACHED,
-  PRELOAD_JS_POSTFIX,
+  PRELOAD_JS_POSTFIX_REGEX,
 } from '../constants'
 import {
   compileManifest,
@@ -17,6 +17,7 @@ import {
 import type { RenderAppProps } from '../types'
 import { getPathFromLoaderPath } from '../utils/cleanUrl'
 import { toAbsoluteUrl } from '../utils/toAbsolute'
+import { toServerOutputPath } from '../utils/toServerOutputPath'
 import type { One } from '../vite/types'
 import type { RouteInfoCompiled } from './createRoutesManifest'
 import { setSSRLoaderData } from './ssrLoaderData'
@@ -24,6 +25,22 @@ import { getFetchStaticHtml } from './staticHtmlFetcher'
 
 const debugRouter = process.env.ONE_DEBUG_ROUTER
 
+// Bounded map helper: prevents unbounded memory growth by evicting the oldest
+// entry when the map exceeds the specified maximum size. Uses insertion order
+// (Map preserves insertion order) — the first-inserted entry is evicted first.
+const MODULE_CACHE_MAX = 500
+function setBounded<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  if (map.has(key)) {
+    map.set(key, value)
+    return
+  }
+  if (map.size >= max) {
+    const firstKey = map.keys().next().value
+    if (firstKey !== undefined) map.delete(firstKey as K)
+  }
+  map.set(key, value)
+}
+
 // forwards response headers to a hono context, preserving individual
 // set-cookie values (Headers.forEach joins them into one unparseable string)
 function forwardHeaders(response: Response, context: { header: Function }) {
@@ -164,9 +181,7 @@ export async function oneServe(
     // cold path - async import
     return (async () => {
       const pathToResolve = serverPath || lazyKey || ''
-      const resolvedPath = pathToResolve.includes(`${outDir}/server`)
-        ? pathToResolve
-        : join('./', `${outDir}/server`, pathToResolve)
+      const resolvedPath = toServerOutputPath(pathToResolve, outDir)
 
       let routeExported: any
       if (moduleImportCache.has(cacheKey)) {
@@ -177,14 +192,14 @@ export async function oneServe(
             ? await options.lazyRoutes.pages[lazyKey]()
             : await import(toAbsoluteUrl(resolvedPath))
           : await import(toAbsoluteUrl(serverPath!))
-        moduleImportCache.set(cacheKey, routeExported)
+        setBounded(moduleImportCache, cacheKey, routeExported, MODULE_CACHE_MAX)
       }
 
       const loader = routeExported?.loader || null
-      loaderCache.set(cacheKey, loader)
+      setBounded(loaderCache, cacheKey, loader, MODULE_CACHE_MAX)
       // also cache loaderCache export for coalescing
       const loaderCacheFn = routeExported?.loaderCache ?? null
-      loaderCacheFnMap.set(cacheKey, loaderCacheFn)
+      setBounded(loaderCacheFnMap, cacheKey, loaderCacheFn, MODULE_CACHE_MAX)
       return loader
     })()
   }
@@ -314,7 +329,8 @@ export async function oneServe(
       }
       // both vite and rolldown-vite replace brackets with underscores in output filenames
       const fileName = route.page.slice(1).replace(/\[/g, '_').replace(/\]/g, '_')
-      const apiFile = join(outDir, 'api', fileName + (apiCJS ? '.cjs' : '.js'))
+      // posix matches the serverJsPath/builtMiddlewares producer convention
+      const apiFile = posix.join(outDir, 'api', fileName + (apiCJS ? '.cjs' : '.js'))
       return await import(toAbsoluteUrl(apiFile))
     },
 
@@ -328,9 +344,7 @@ export async function oneServe(
 
     async handleLoader({ route, loaderProps }) {
       const routeFile = (route as any).routeFile || route.file
-      const serverPath = route.file.includes(`${outDir}/server`)
-        ? route.file
-        : join('./', `${outDir}/server`, route.file)
+      const serverPath = toServerOutputPath(route.file, outDir)
 
       let loader: Function | null
       try {
@@ -940,7 +954,11 @@ url: ${url}`)
 
   // TODO make this inside each page, need to make loader urls just be REGULAR_URL + loaderpostfix
   app.get('*', async (c, next) => {
-    if (c.req.path.endsWith(PRELOAD_JS_POSTFIX)) {
+    // regex match (not exact CACHE_KEY suffix) — see constants.ts:
+    // PRELOAD_JS_POSTFIX_REGEX. handles dynamic segments and the rare
+    // CACHE_KEY-drift case by funnelling misses through the graceful
+    // empty-200 below instead of the static-handler 404.
+    if (PRELOAD_JS_POSTFIX_REGEX.test(c.req.path)) {
       // TODO handle dynamic segments (i think the below loader has some logic for this)
       if (!preloads[c.req.path]) {
         // no preload exists 200 gracefully
@@ -950,7 +968,7 @@ url: ${url}`)
       }
     }
 
-    if (c.req.path.endsWith(CSS_PRELOAD_JS_POSTFIX)) {
+    if (CSS_PRELOAD_JS_POSTFIX_REGEX.test(c.req.path)) {
       // Return empty resolved promise if no CSS preload exists for this route
       if (!cssPreloads?.[c.req.path]) {
         c.header('Content-Type', 'text/javascript')

package/src/server/setupBuildOptions.ts

@@ -1,8 +1,17 @@
+import { setCacheKey } from '../constants'
 import type { One } from '../vite/types'
 
 export function setupBuildInfo(buildInfo: One.BuildInfo) {
-  // ensure cache key matches build
-  process.env.ONE_CACHE_KEY ||= buildInfo.constants.CACHE_KEY
+  // ensure cache key matches build. env var is for child workers spawned later;
+  // setCacheKey rebinds the in-memory postfixes for the current process so any
+  // code that imported constants before setupBuildInfo ran (e.g. workerHandler
+  // pulled in by serve-worker's static import graph) sees the pinned value.
+  // headless-server may not pass `constants` — skip gracefully.
+  const key = buildInfo.constants?.CACHE_KEY
+  if (key) {
+    process.env.ONE_CACHE_KEY ||= key
+    setCacheKey(key)
+  }
   process.env.ONE_DEFAULT_RENDER_MODE ||=
     buildInfo.oneOptions?.web?.defaultRenderMode || 'ssg'
 }

package/src/server/workerHandler.ts

@@ -1,7 +1,7 @@
 import {
-  CSS_PRELOAD_JS_POSTFIX,
+  CSS_PRELOAD_JS_POSTFIX_REGEX,
   LOADER_JS_POSTFIX_UNCACHED,
-  PRELOAD_JS_POSTFIX,
+  PRELOAD_JS_POSTFIX_REGEX,
 } from '../constants'
 import {
   compileManifest,
@@ -597,8 +597,12 @@ export function createWorkerHandler(options: WorkerHandlerOptions) {
       }
     }
 
-    // 2. preload endpoints (empty response if no preload exists)
-    if (pathname.endsWith(PRELOAD_JS_POSTFIX)) {
+    // 2. preload endpoints (empty response if no preload exists).
+    // regex match (not exact CACHE_KEY suffix) — see constants.ts:
+    // PRELOAD_JS_POSTFIX_REGEX. handles dynamic segments and the rare
+    // CACHE_KEY-drift case by funnelling misses through the graceful
+    // empty-200 below instead of the static-handler 404.
+    if (PRELOAD_JS_POSTFIX_REGEX.test(pathname)) {
       if (!currentPreloads[pathname]) {
         return new Response('', {
           headers: { 'Content-Type': 'text/javascript' },
@@ -608,7 +612,7 @@ export function createWorkerHandler(options: WorkerHandlerOptions) {
       return null
     }
 
-    if (pathname.endsWith(CSS_PRELOAD_JS_POSTFIX)) {
+    if (CSS_PRELOAD_JS_POSTFIX_REGEX.test(pathname)) {
       if (!currentCssPreloads?.[pathname]) {
         return new Response('export default Promise.resolve()', {
           headers: { 'Content-Type': 'text/javascript' },

package/src/useLoader.ts

@@ -90,8 +90,26 @@ registerDevtoolsFunction('recordLoaderTiming', recordLoaderTiming)
 const loaderState: Record<string, LoaderStateEntry> = {}
 const subscribers = new Set<() => void>()
 
+// Prevent unbounded growth of loaderState by pruning the oldest entry when
+// we exceed this limit. Most apps navigate a limited set of routes, but
+// dynamic params (e.g. /users/:id) can generate thousands of unique keys.
+const LOADER_STATE_MAX = 200
+const loaderStateKeys: string[] = []
+
+function setBoundedLoaderState(path: string, entry: LoaderStateEntry) {
+  if (!(path in loaderState)) {
+    loaderStateKeys.push(path)
+    if (loaderStateKeys.length > LOADER_STATE_MAX) {
+      const oldest = loaderStateKeys.shift()!
+      delete loaderState[oldest]
+    }
+  }
+  loaderState[path] = entry
+}
+
 function updateState(path: string, updates: Partial<LoaderStateEntry>) {
-  loaderState[path] = { ...loaderState[path], ...updates }
+  const merged = { ...loaderState[path], ...updates }
+  setBoundedLoaderState(path, merged)
   subscribers.forEach((callback) => {
     callback()
   })
@@ -103,14 +121,15 @@ function subscribe(callback: () => void) {
 }
 
 function getLoaderState(path: string, preloadedData?: any): LoaderStateEntry {
-  if (!loaderState[path]) {
-    loaderState[path] = {
+  if (!(path in loaderState)) {
+    const entry: LoaderStateEntry = {
       data: preloadedData,
       error: undefined,
       promise: undefined,
       state: 'idle',
       hasLoadedOnce: !!preloadedData,
     }
+    setBoundedLoaderState(path, entry)
   }
   return loaderState[path]
 }
@@ -759,6 +778,22 @@ export function useLoader<
 const results = new Map()
 const started = new Map()
 
+// Prevent unbounded growth of useAsyncFn caches. Under sustained client-side
+// navigation with many unique param combinations, these can accumulate large
+// API responses. 100 entries is generous for typical route counts.
+const USE_ASYNC_FN_CACHE_MAX = 100
+
+function setBoundedResults(key: string, value: any) {
+  if (results.size >= USE_ASYNC_FN_CACHE_MAX && !results.has(key)) {
+    const firstKey = results.keys().next().value
+    if (firstKey !== undefined) {
+      results.delete(firstKey as string)
+      started.delete(firstKey as string)
+    }
+  }
+  results.set(key, value)
+}
+
 // maps loader function → its route's loaderData for SSR
 // populated before render in oneServe.ts, cleared after
 // re-export for backwards compat
@@ -780,14 +815,14 @@ function useAsyncFn(val: any, props?: any) {
       if (next instanceof Promise) {
         next = next
           .then((final) => {
-            results.set(key, final)
+            setBoundedResults(key, final)
           })
           .catch((err) => {
             console.error(`Error running loader()`, err)
-            results.set(key, undefined)
+            setBoundedResults(key, undefined)
           })
       }
-      results.set(key, next)
+      setBoundedResults(key, next)
     }
   }
 

package/src/utils/buildOutputPointer.test.ts

@@ -0,0 +1,97 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import FSExtra from 'fs-extra'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  buildOutputPointerPath,
+  resolveServeOutDir,
+  writeBuildOutputPointer,
+} from './buildOutputPointer'
+
+describe('build output pointer', () => {
+  const originalCwd = process.cwd()
+  let tempRoot = ''
+
+  beforeEach(() => {
+    tempRoot = mkdtempSync(join(tmpdir(), 'one-build-pointer-'))
+    process.chdir(tempRoot)
+  })
+
+  afterEach(async () => {
+    process.chdir(originalCwd)
+    vi.restoreAllMocks()
+    await FSExtra.remove(tempRoot)
+  })
+
+  it('prefers an explicit serve outDir', async () => {
+    await FSExtra.ensureDir('build-out')
+    await FSExtra.writeJSON(join('build-out', 'buildInfo.json'), {})
+    await writeBuildOutputPointer('build-out')
+
+    expect(await resolveServeOutDir('manual-out')).toBe('manual-out')
+  })
+
+  it('preserves serving from inside the output directory', async () => {
+    await FSExtra.writeJSON('buildInfo.json', {})
+    await FSExtra.ensureDir('build-out')
+    await FSExtra.writeJSON(join('build-out', 'buildInfo.json'), {})
+    await writeBuildOutputPointer('build-out')
+
+    expect(await resolveServeOutDir()).toBe('.')
+  })
+
+  it('resolves the outDir written by build', async () => {
+    await FSExtra.ensureDir('build-out')
+    await FSExtra.writeJSON(join('build-out', 'buildInfo.json'), {})
+
+    await writeBuildOutputPointer('build-out')
+
+    expect(await FSExtra.readJSON(buildOutputPointerPath)).toEqual({
+      outDir: 'build-out',
+    })
+    expect(await resolveServeOutDir()).toBe('build-out')
+  })
+
+  it('falls back to dist when the pointer is stale', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await writeBuildOutputPointer('missing-out')
+
+    expect(await resolveServeOutDir()).toBe('dist')
+    // both the stale-pointer warning and the missing-dist warning fire
+    expect(warn).toHaveBeenCalledTimes(2)
+    expect(warn.mock.calls[0][0]).toMatch(/build-pointer\.json points to/)
+    expect(warn.mock.calls[1][0]).toMatch(/no build-output pointer/)
+  })
+
+  it('falls back to dist when no pointer exists and warns about missing dist', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    expect(await resolveServeOutDir()).toBe('dist')
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toMatch(/no build-output pointer/)
+  })
+
+  it('does not warn when falling back to an existing dist/ build', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    await FSExtra.ensureDir('dist')
+    await FSExtra.writeJSON(join('dist', 'buildInfo.json'), {})
+
+    expect(await resolveServeOutDir()).toBe('dist')
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('warns when the pointer write fails', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const writeSpy = vi
+      .spyOn(FSExtra, 'writeJSON')
+      .mockRejectedValueOnce(new Error('permission denied'))
+
+    await writeBuildOutputPointer('build-out')
+
+    expect(writeSpy).toHaveBeenCalled()
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toMatch(/could not write build-output pointer/)
+  })
+})

package/src/utils/buildOutputPointer.ts

@@ -0,0 +1,71 @@
+import { dirname, join } from 'node:path'
+import FSExtra from 'fs-extra'
+import { toAbsolute } from './toAbsolute'
+
+// stored under the project cwd; one build and one serve should run from the same root.
+export const buildOutputPointerPath = join(
+  'node_modules',
+  '.cache',
+  'one',
+  'build-pointer.json'
+)
+
+type BuildOutputPointer = {
+  outDir?: string
+}
+
+export async function writeBuildOutputPointer(outDir: string) {
+  try {
+    const pointerPath = toAbsolute(buildOutputPointerPath)
+    await FSExtra.ensureDir(dirname(pointerPath))
+    await FSExtra.writeJSON(pointerPath, { outDir })
+  } catch (err) {
+    // surface the failure so `one serve` doesn't later fall back to `dist/`
+    // with no breadcrumb when a custom outDir was used.
+    console.warn(
+      `[one build] could not write build-output pointer (${buildOutputPointerPath}). \`one serve\` will fall back to 'dist/' unless you pass --outDir.`,
+      err instanceof Error ? err.message : err
+    )
+  }
+}
+
+export async function resolveServeOutDir(outDir?: string) {
+  if (outDir) {
+    return outDir
+  }
+
+  if (FSExtra.existsSync('buildInfo.json')) {
+    return '.'
+  }
+
+  // ENOENT here is the common case (no pointer written yet); only warn on
+  // unexpected read errors.
+  let pointer: BuildOutputPointer | undefined
+  try {
+    pointer = (await FSExtra.readJSON(buildOutputPointerPath)) as BuildOutputPointer
+  } catch (err: any) {
+    if (err?.code && err.code !== 'ENOENT') {
+      console.warn(
+        `[one serve] could not read build-output pointer (${buildOutputPointerPath}):`,
+        err.message ?? err
+      )
+    }
+  }
+
+  if (pointer?.outDir) {
+    if (await FSExtra.pathExists(join(pointer.outDir, 'buildInfo.json'))) {
+      return pointer.outDir
+    }
+    console.warn(
+      `[one serve] build-pointer.json points to '${pointer.outDir}/' but no buildInfo.json was found there. run \`one build\` to refresh the marker.`
+    )
+  }
+
+  if (!FSExtra.existsSync('dist/buildInfo.json')) {
+    console.warn(
+      `[one serve] no build-output pointer and no 'dist/buildInfo.json'. did \`one build\` run from this cwd? pass --outDir to point at the build output.`
+    )
+  }
+
+  return 'dist'
+}

package/src/utils/dynamicImport.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest'
+import { isChunkLoadError, loadWithRetry } from './dynamicImport'
+
+const instantDelay = () => Promise.resolve()
+const chunkError = () =>
+  new Error('Failed to fetch dynamically imported module: /assets/EditorPane.js')
+
+// let the all-microtask retry chain (instantDelay resolves synchronously) plus
+// the final pending-promise branch fully drain before asserting.
+const drain = () => new Promise((r) => setTimeout(r, 0))
+
+describe('isChunkLoadError', () => {
+  it('matches the chrome / firefox / safari chunk-load messages, nothing else', () => {
+    expect(isChunkLoadError(new Error('Failed to fetch dynamically imported module: /a'))).toBe(
+      true
+    )
+    expect(isChunkLoadError(new Error('error loading dynamically imported module: /a'))).toBe(
+      true
+    )
+    expect(isChunkLoadError(new Error('Importing a module script failed.'))).toBe(true)
+    expect(isChunkLoadError('Failed to fetch dynamically imported module')).toBe(true)
+    expect(isChunkLoadError(new Error('TypeError: x is not a function'))).toBe(false)
+  })
+})
+
+describe('loadWithRetry', () => {
+  it('resolves on first success without retrying or recovering', async () => {
+    const loader = vi.fn().mockResolvedValue({ default: 'ok' })
+    const delay = vi.fn(instantDelay)
+    const onChunkErrorExhausted = vi.fn(() => false)
+    await expect(loadWithRetry(loader, { delay, onChunkErrorExhausted })).resolves.toEqual({
+      default: 'ok',
+    })
+    expect(loader).toHaveBeenCalledTimes(1)
+    expect(delay).not.toHaveBeenCalled()
+    expect(onChunkErrorExhausted).not.toHaveBeenCalled()
+  })
+
+  it('retries a transient rejection then resolves, re-invoking the loader each attempt', async () => {
+    const loader = vi
+      .fn()
+      .mockRejectedValueOnce(chunkError())
+      .mockRejectedValueOnce(chunkError())
+      .mockResolvedValue({ default: 'ok' })
+    const delay = vi.fn(instantDelay)
+    const onChunkErrorExhausted = vi.fn(() => false)
+    await expect(
+      loadWithRetry(loader, { attempts: 3, delay, onChunkErrorExhausted })
+    ).resolves.toEqual({ default: 'ok' })
+    expect(loader).toHaveBeenCalledTimes(3)
+    expect(delay).toHaveBeenCalledTimes(2)
+    expect(onChunkErrorExhausted).not.toHaveBeenCalled()
+  })
+
+  it('exhausts retries on a persistent chunk error, recovers once, and stays pending', async () => {
+    const loader = vi.fn().mockRejectedValue(chunkError())
+    const delay = vi.fn(instantDelay)
+    const onChunkErrorExhausted = vi.fn(() => true) // a reload was scheduled
+    const settled = vi.fn()
+    void loadWithRetry(loader, { attempts: 2, delay, onChunkErrorExhausted }).then(
+      settled,
+      settled
+    )
+    await drain()
+    expect(loader).toHaveBeenCalledTimes(3) // initial + 2 retries
+    expect(onChunkErrorExhausted).toHaveBeenCalledTimes(1)
+    // the page is tearing down for the reload — the promise must never settle so
+    // it can't flash a broken/blank tree.
+    expect(settled).not.toHaveBeenCalled()
+  })
+
+  it('rethrows a non-chunk error without recovering', async () => {
+    const loader = vi.fn().mockRejectedValue(new Error('boom: a real bug'))
+    const delay = vi.fn(instantDelay)
+    const onChunkErrorExhausted = vi.fn(() => true)
+    await expect(
+      loadWithRetry(loader, { attempts: 1, delay, onChunkErrorExhausted })
+    ).rejects.toThrow('boom: a real bug')
+    expect(loader).toHaveBeenCalledTimes(2)
+    expect(onChunkErrorExhausted).not.toHaveBeenCalled()
+  })
+
+  it('rethrows a chunk error when the reload was debounced away', async () => {
+    const loader = vi.fn().mockRejectedValue(chunkError())
+    const delay = vi.fn(instantDelay)
+    const onChunkErrorExhausted = vi.fn(() => false) // debounced, no reload happened
+    await expect(
+      loadWithRetry(loader, { attempts: 1, delay, onChunkErrorExhausted })
+    ).rejects.toThrow('Failed to fetch dynamically imported module')
+    expect(onChunkErrorExhausted).toHaveBeenCalledTimes(1)
+  })
+})

package/src/utils/dynamicImport.ts

@@ -9,17 +9,23 @@ export const dynamicImport = (path: string) => {
     return Promise.resolve(undefined)
   }
 
-  if (process.env.TAMAGUI_TARGET !== 'native') {
-    return import(
-      /* @vite-ignore */
-      path
-    ).catch((err) => {
-      if (process.env.ONE_SKEW_PROTECTION !== 'false' && isChunkLoadError(err)) {
-        handleSkewError()
-      }
-      throw err
-    })
-  }
+  // retry a transient chunk-fetch failure in place before giving up, then fall
+  // back to one's debounced reload. the in-place retry matters because a single
+  // rejection permanently poisons callers that memoize the loader result — most
+  // notably React.lazy, which caches the FIRST settled value (rejection
+  // included) and re-throws it forever without re-invoking the loader. the retry
+  // is always cheap; only the reload honors the ONE_SKEW_PROTECTION opt-out.
+  return loadWithRetry(
+    () =>
+      import(
+        /* @vite-ignore */
+        path
+      ),
+    {
+      onChunkErrorExhausted: () =>
+        process.env.ONE_SKEW_PROTECTION !== 'false' ? handleSkewError() : false,
+    }
+  )
 }
 
 const CHUNK_ERROR_PATTERNS = [
@@ -33,12 +39,73 @@ export function isChunkLoadError(err: unknown): boolean {
   return CHUNK_ERROR_PATTERNS.some((p) => msg.includes(p))
 }
 
-export function handleSkewError() {
-  if (typeof window === 'undefined') return
+// debounced one-time reload to recover from a deploy skew or a poisoned dev
+// module graph. returns whether it actually scheduled a reload (false when
+// debounced away within the cooldown, or on the server) so callers like
+// loadWithRetry can decide whether to keep waiting for the teardown or surface
+// the underlying error.
+export function handleSkewError(): boolean {
+  if (typeof window === 'undefined') return false
   const key = '__one_skew_reload'
   const last = sessionStorage.getItem(key)
   if (!last || Date.now() - Number(last) > 10_000) {
     sessionStorage.setItem(key, String(Date.now()))
     window.location.reload()
+    return true
+  }
+  return false
+}
+
+// extra attempts after the first before giving up. a transient chunk fetch
+// (ECONNRESET / dev-server 5xx / timeout under load) usually recovers on the
+// next try when the failure is the top-level chunk.
+export const CHUNK_RETRY_ATTEMPTS = 3
+// linear backoff between chunk retries: ride out a brief hiccup, not a long
+// outage.
+export const CHUNK_RETRY_DELAY_MS = 500
+
+const realDelay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+// wraps a dynamic-import loader so a transient rejection is retried with backoff
+// before it settles, instead of permanently poisoning a caller that memoizes the
+// result (e.g. React.lazy — see dynamicImport above, and lazyWithRetry). when
+// retries are exhausted on a chunk-load error, recover via the injected reload
+// (defaults to one's debounced handleSkewError); the reload tears the page down,
+// so the returned promise is left pending rather than rejecting into a surviving
+// tree. `delay` + `onChunkErrorExhausted` are injectable so this is unit-testable
+// without real timers or a real location.reload.
+export async function loadWithRetry<T>(
+  loader: () => Promise<T>,
+  options: {
+    attempts?: number
+    delayMs?: number
+    delay?: (ms: number) => Promise<void>
+    onChunkErrorExhausted?: () => boolean
+  } = {}
+): Promise<T> {
+  const attempts = options.attempts ?? CHUNK_RETRY_ATTEMPTS
+  const delayMs = options.delayMs ?? CHUNK_RETRY_DELAY_MS
+  const delay = options.delay ?? realDelay
+  const recover = options.onChunkErrorExhausted ?? handleSkewError
+
+  const attempt = async (retriesLeft: number): Promise<T> => {
+    try {
+      return await loader()
+    } catch (err) {
+      if (retriesLeft > 0) {
+        await delay(delayMs)
+        return attempt(retriesLeft - 1)
+      }
+      // out of retries: a chunk-load failure is a dev module-graph poison or a
+      // prod deploy skew — recover via the debounced reload. the reload tears the
+      // page down, so leave this promise pending (resolving/rejecting would
+      // flash a broken tree). if the reload was debounced away, surface the real
+      // error so it isn't swallowed.
+      if (isChunkLoadError(err) && recover()) {
+        return new Promise<T>(() => {})
+      }
+      throw err
+    }
   }
+  return attempt(attempts)
 }