one 1.16.8 → 1.16.9

package/src/headless.tsx

@@ -1,5 +1,6 @@
 import './setup'
 
+import type { OneLinkingConfig } from './link/getLinking'
 import { Root } from './Root'
 import { resolveClientLoader } from './clientLoaderResolver'
 import { render } from './render'
@@ -13,6 +14,7 @@ export type CreateHeadlessAppProps = {
   routerRoot: string
   path?: string
   flags?: One.Flags
+  linking?: OneLinkingConfig
   getSetupPromise?: () => Promise<unknown>
 }
 
@@ -34,6 +36,7 @@ export function createApp(options: CreateHeadlessAppProps) {
           flags={options.flags}
           routes={options.routes}
           routerRoot={options.routerRoot}
+          linking={options.linking}
           path={
             options.path || (typeof window !== 'undefined' ? window.location.href : '/')
           }

package/src/index.ts

@@ -77,7 +77,9 @@ export {
   useSegments,
   useUnstableGlobalHref,
 } from './hooks'
+export { useSitemap, type SitemapType } from './router/sitemap'
 export { href } from './href'
+export { getLinking, type OneLinkingConfig } from './link/getLinking'
 // components
 export { Stack } from './layouts/Stack'
 export { Tabs } from './layouts/Tabs'

package/src/link/getLinking.ts

@@ -0,0 +1,56 @@
+export type OneLinkingConfig = {
+  /**
+   * Custom app scheme or schemes. Each scheme is expanded to double- and
+   * triple-slashed URL prefixes.
+   */
+  scheme?: string | string[]
+  /**
+   * Fully qualified URL prefixes to strip before matching routes.
+   *
+   * For host-bearing custom scheme URLs, include the host:
+   * `myapp://app`.
+   */
+  prefixes?: string[]
+  filter?: (url: string) => boolean
+}
+
+export type NormalizedOneLinkingConfig = {
+  prefixes: string[]
+  filter?: (url: string) => boolean
+}
+
+export function getLinking(config: OneLinkingConfig = {}): OneLinkingConfig {
+  return config
+}
+
+export function normalizeLinkingConfig(
+  config: OneLinkingConfig | undefined,
+  defaultPrefixes: string[] = []
+): NormalizedOneLinkingConfig {
+  // merge: defaults from the native manifest combine with whatever the user
+  // provides via scheme/prefixes, so URLs from any registered scheme are
+  // recognized even when the user only mentions a subset
+  const merged = [
+    ...defaultPrefixes,
+    ...getSchemePrefixes(config?.scheme),
+    ...(config?.prefixes ?? []),
+  ]
+
+  return {
+    prefixes: dedupe(merged),
+    filter: config?.filter,
+  }
+}
+
+function getSchemePrefixes(scheme: string | string[] | undefined): string[] {
+  const schemes = Array.isArray(scheme) ? scheme : scheme ? [scheme] : []
+
+  return schemes.flatMap((value) => {
+    const normalized = value.replace(/:\/+$/, '')
+    return [`${normalized}://`, `${normalized}:///`]
+  })
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))]
+}

package/src/link/linking.native.ts

@@ -62,6 +62,13 @@ export function getRootURL(): string {
   return _rootURL
 }
 
+export function getDefaultLinkingPrefixes(): string[] {
+  return Linking.collectManifestSchemes?.().flatMap((scheme) => {
+    const normalized = scheme.replace(/:\/+$/, '')
+    return [`${normalized}://`, `${normalized}:///`]
+  }) ?? []
+}
+
 export function addEventListener(listener: (url: string) => void) {
   let callback: (({ url }: { url: string }) => void) | undefined
 

package/src/link/linking.ts

@@ -12,6 +12,10 @@ export function getRootURL(): string {
   return '/'
 }
 
+export function getDefaultLinkingPrefixes(): string[] {
+  return []
+}
+
 export function addEventListener(listener: (url: string) => void) {
   if (typeof window === 'undefined') {
     return () => {}

package/src/metro-config/getViteMetroPluginOptions.ts

@@ -20,12 +20,14 @@ export function getViteMetroPluginOptions({
   projectRoot,
   relativeRouterRoot,
   ignoredRouteFiles,
+  linking,
   userDefaultConfigOverrides,
   setupFile,
 }: {
   projectRoot: string
   relativeRouterRoot: string
   ignoredRouteFiles?: Array<`**/*${string}`>
+  linking?: unknown
   userDefaultConfigOverrides?: NonNullable<
     Parameters<typeof metroPlugin>[0]
   >['defaultConfigOverrides']
@@ -236,6 +238,7 @@ export function getViteMetroPluginOptions({
             ),
             ONE_ROUTER_ROOT_FOLDER_NAME: relativeRouterRoot,
             ONE_ROUTER_REQUIRE_CONTEXT_REGEX_STRING: routerRequireContextRegexString,
+            ONE_ROUTER_LINKING_CONFIG: linking,
             ONE_SETUP_FILE_NATIVE: (() => {
               if (!setupFile) return undefined
               // Extract native setup file path

package/src/router/Route.tsx

@@ -4,7 +4,7 @@ import type { ErrorBoundaryProps } from '../views/Try'
 import type { LoaderProps } from '../types'
 import type { One } from '../vite/types'
 import type { ParamValidator, RouteValidationFn } from '../validateParams'
-import { getLinking } from './linkingConfig'
+import { getResolvedLinking } from './linkingConfig'
 import { getContextKey } from './matchers'
 import { mergeDynamicParams } from './params'
 import { routeInfo } from './router'
@@ -153,7 +153,7 @@ function getParamsFromCurrentUrl(route?: {
   path?: string
   params?: Record<string, string | undefined>
 }): Record<string, any> | undefined {
-  const linking = getLinking()
+  const linking = getResolvedLinking()
   if (!linking?.getStateFromPath) return undefined
   const path =
     routeInfo?.unstable_globalHref ||

package/src/router/getLinkingConfig.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { normalizeLinkingConfig } from '../link/getLinking'
+import { getRoutes } from './getRoutes'
+import { getLinkingConfig } from './getLinkingConfig'
+import { getMockContext } from '../testing-utils'
+
+describe('getLinkingConfig', () => {
+  it('expands configured schemes into prefixes', () => {
+    const routes = getRoutes(getMockContext(['_layout.tsx', 'index.tsx']))!
+    const linking = getLinkingConfig(routes, true, {
+      scheme: 'threepunchconvo',
+    })
+
+    expect(linking.prefixes).toEqual([
+      'threepunchconvo://',
+      'threepunchconvo:///',
+    ])
+  })
+
+  it('merges explicit prefixes with scheme-derived prefixes', () => {
+    const routes = getRoutes(getMockContext(['_layout.tsx', 'index.tsx']))!
+    const linking = getLinkingConfig(routes, true, {
+      scheme: 'threepunchconvo',
+      prefixes: ['threepunchconvo://app'],
+    })
+
+    expect(linking.prefixes).toEqual([
+      'threepunchconvo://',
+      'threepunchconvo:///',
+      'threepunchconvo://app',
+    ])
+  })
+})
+
+describe('normalizeLinkingConfig', () => {
+  it('merges manifest-default prefixes with user-supplied scheme/prefixes', () => {
+    const result = normalizeLinkingConfig(
+      { scheme: 'foo', prefixes: ['https://example.test/app'] },
+      ['bar://', 'bar:///']
+    )
+
+    expect(result.prefixes).toEqual([
+      'bar://',
+      'bar:///',
+      'foo://',
+      'foo:///',
+      'https://example.test/app',
+    ])
+  })
+
+  it('falls back to manifest-default prefixes when nothing is configured', () => {
+    const result = normalizeLinkingConfig(undefined, ['bar://', 'bar:///'])
+    expect(result.prefixes).toEqual(['bar://', 'bar:///'])
+  })
+
+  it('dedupes overlapping defaults and configured prefixes', () => {
+    const result = normalizeLinkingConfig(
+      { scheme: 'foo' },
+      ['foo://', 'foo:///']
+    )
+    expect(result.prefixes).toEqual(['foo://', 'foo:///'])
+  })
+})

package/src/router/getLinkingConfig.ts

@@ -3,10 +3,16 @@ import type { State } from '../fork/getPathFromState'
 import { getReactNavigationConfig, type Screen } from '../getReactNavigationConfig'
 import {
   addEventListener,
+  getDefaultLinkingPrefixes,
   getInitialURL,
   getPathFromState,
   getStateFromPath,
 } from '../link/linking'
+import {
+  normalizeLinkingConfig,
+  type OneLinkingConfig,
+} from '../link/getLinking'
+import { evictOldest } from '../utils/evictOldest'
 import type { RouteNode } from './Route'
 
 export function getNavigationConfig(
@@ -23,10 +29,19 @@ export type OneLinkingOptions = LinkingOptions<object> & {
   getPathFromState?: typeof getPathFromState
 }
 
-export function getLinkingConfig(routes: RouteNode, metaOnly = true): OneLinkingOptions {
+export function getLinkingConfig(
+  routes: RouteNode,
+  metaOnly = true,
+  linking?: OneLinkingConfig
+): OneLinkingOptions {
   const config = getNavigationConfig(routes, metaOnly)
+  const resolvedLinking = normalizeLinkingConfig(
+    linking,
+    getDefaultLinkingPrefixes()
+  )
   return {
-    prefixes: [],
+    prefixes: resolvedLinking.prefixes,
+    filter: resolvedLinking.filter,
     // @ts-expect-error
     config,
     // A custom getInitialURL is used on native to ensure the app always starts at
@@ -53,7 +68,15 @@ export function getLinkingConfig(routes: RouteNode, metaOnly = true): OneLinking
 
 export const stateCache = new Map<string, any>()
 
-/** We can reduce work by memoizing the state by the pathname. This only works because the options (linking config) theoretically never change.  */
+const STATE_CACHE_THRESHOLD = 5000
+const STATE_CACHE_EVICTION = 1000
+
+export function clearStateCache() {
+  stateCache.clear()
+}
+
+/** memoize getStateFromPath by pathname. cache is cleared when the route tree
+ * or linking config changes (see ensureBaseLinkingConfig in linkingConfig.ts). */
 function getStateFromPathMemoized(
   path: string,
   options: Parameters<typeof getStateFromPath>[1]
@@ -63,6 +86,7 @@ function getStateFromPathMemoized(
     return cached
   }
   const result = getStateFromPath(path, options)
+  evictOldest(stateCache, STATE_CACHE_THRESHOLD, STATE_CACHE_EVICTION)
   stateCache.set(path, result)
   return result
 }

package/src/router/getRouteInfo.ts

@@ -4,14 +4,14 @@ import { stripBaseUrl } from '../fork/getStateFromPath-mods'
 import type { OneRouter } from '../interfaces/router'
 import { getNormalizedStatePath, type UrlObject } from './getNormalizedStatePath'
 import { isIndexPath } from './isIndexPath'
-import { getLinking } from './linkingConfig'
+import { getResolvedLinking } from './linkingConfig'
 
 export function getRouteInfo(state: OneRouter.ResultState) {
   return getRouteInfoFromState(
     (state: Parameters<typeof originalGetPathFromState>[0], asPath: boolean) => {
       return getPathDataFromState(state, {
         screens: [],
-        ...getLinking()?.config,
+        ...getResolvedLinking()?.config,
         preserveDynamicRoutes: asPath,
         preserveGroups: asPath,
       })

package/src/router/linkingConfig.ts

@@ -1,7 +1,9 @@
 import { isWebClient } from '../constants'
 import type { OneRouter } from '../interfaces/router'
+import type { OneLinkingConfig } from '../link/getLinking'
 import { evictOldest } from '../utils/evictOldest'
 import {
+  clearStateCache,
   getLinkingConfig as createLinkingConfig,
   type OneLinkingOptions,
 } from './getLinkingConfig'
@@ -12,12 +14,13 @@ let linkingConfig: OneLinkingOptions | undefined
 // cache the base linking config (route-tree dependent, not URL-dependent)
 let cachedBaseLinkingConfig: OneLinkingOptions | undefined
 let cachedRouteNodeForLinking: RouteNode | null = null
+let cachedLinkingConfigKey = ''
 
 // cache getStateFromPath results by path for SSR performance
 // same path always produces the same navigation state (route tree is static in prod)
 const ssrStateCache = new Map<string, OneRouter.ResultState | undefined>()
 
-export function getLinking() {
+export function getResolvedLinking() {
   return linkingConfig
 }
 
@@ -33,13 +36,25 @@ export function resetLinking() {
  * Ensure the base linking config is initialized for a given route tree.
  * Does not set any per-request state.
  */
-export function ensureBaseLinkingConfig(routeNode: RouteNode | null) {
+export function ensureBaseLinkingConfig(
+  routeNode: RouteNode | null,
+  linking?: OneLinkingConfig
+) {
+  const linkingConfigKey = getLinkingConfigKey(linking)
   if (
     routeNode &&
-    (routeNode !== cachedRouteNodeForLinking || !cachedBaseLinkingConfig)
+    (routeNode !== cachedRouteNodeForLinking ||
+      linkingConfigKey !== cachedLinkingConfigKey ||
+      !cachedBaseLinkingConfig)
   ) {
-    cachedBaseLinkingConfig = createLinkingConfig(routeNode)
+    // route tree or linking config changed — drop memoized navigation states
+    // so getStateFromPathMemoized doesn't return entries computed against
+    // the previous configuration
+    clearStateCache()
+    ssrStateCache.clear()
+    cachedBaseLinkingConfig = createLinkingConfig(routeNode, true, linking)
     cachedRouteNodeForLinking = routeNode
+    cachedLinkingConfigKey = linkingConfigKey
   }
 }
 
@@ -49,11 +64,12 @@ export function ensureBaseLinkingConfig(routeNode: RouteNode | null) {
  */
 export function getSSRInitialState(
   routeNode: RouteNode | null,
-  initialLocation: URL
+  initialLocation: URL,
+  linking?: OneLinkingConfig
 ): OneRouter.ResultState | undefined {
   if (!routeNode) return undefined
 
-  ensureBaseLinkingConfig(routeNode)
+  ensureBaseLinkingConfig(routeNode, linking)
   if (!cachedBaseLinkingConfig) return undefined
 
   const path = initialLocation.pathname + (initialLocation.search || '')
@@ -70,13 +86,14 @@ export function getSSRInitialState(
 
 export function setupLinking(
   routeNode: RouteNode | null,
-  initialLocation?: URL
+  initialLocation?: URL,
+  linking?: OneLinkingConfig
 ): OneRouter.ResultState | undefined {
   let initialState: OneRouter.ResultState | undefined
 
   if (routeNode) {
     // reuse ensureBaseLinkingConfig to avoid duplicating cache logic
-    ensureBaseLinkingConfig(routeNode)
+    ensureBaseLinkingConfig(routeNode, linking)
 
     // shallow copy so per-request mutations (getInitialURL) don't affect cache
     linkingConfig = { ...cachedBaseLinkingConfig! }
@@ -101,3 +118,30 @@ export function setupLinking(
 
   return initialState
 }
+
+// each unique filter function gets a stable id so reference-equal filters
+// share a cache key while distinct filters invalidate it
+const filterIds = new WeakMap<NonNullable<OneLinkingConfig['filter']>, number>()
+let filterIdCounter = 0
+function getFilterId(filter: OneLinkingConfig['filter']) {
+  if (!filter) return 0
+  let id = filterIds.get(filter)
+  if (id === undefined) {
+    id = ++filterIdCounter
+    filterIds.set(filter, id)
+  }
+  return id
+}
+
+function getLinkingConfigKey(linking: OneLinkingConfig | undefined) {
+  // sort prefixes/schemes so ordering doesn't cause spurious cache misses
+  const schemes = Array.isArray(linking?.scheme)
+    ? [...linking.scheme].sort()
+    : (linking?.scheme ?? null)
+  const prefixes = linking?.prefixes ? [...linking.prefixes].sort() : null
+  return JSON.stringify({
+    scheme: schemes,
+    prefixes,
+    filterId: getFilterId(linking?.filter),
+  })
+}

package/src/router/router.ts

@@ -20,6 +20,7 @@ import { Platform } from 'react-native'
 import { devtoolsRegistry } from '../devtools/registry'
 import type { OneRouter } from '../interfaces/router'
 import { resolveHref } from '../link/href'
+import type { OneLinkingConfig } from '../link/getLinking'
 import { openExternalURL } from '../link/openExternalURL'
 import { resolve } from '../link/path'
 import { checkBlocker } from '../useBlocker'
@@ -45,7 +46,7 @@ import type { UrlObject } from './getNormalizedStatePath'
 import { getRouteInfo } from './getRouteInfo'
 import { getRoutes } from './getRoutes'
 import { setLastAction } from './lastAction'
-import { getLinking, resetLinking, setupLinking } from './linkingConfig'
+import { getResolvedLinking, resetLinking, setupLinking } from './linkingConfig'
 import type { RouteNode } from './Route'
 import { sortRoutes } from './sortRoutes'
 import { getQualifiedRouteComponent } from './useScreens'
@@ -214,7 +215,8 @@ let cachedContext: One.RouteContext | null = null
 export function initialize(
   context: One.RouteContext,
   ref: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>,
-  initialLocation?: URL
+  initialLocation?: URL,
+  linking?: OneLinkingConfig
 ) {
   cleanUpState()
 
@@ -281,7 +283,7 @@ export function initialize(
   }
 
   navigationRef = ref as unknown as OneRouter.NavigationRef
-  setupLinkingAndRouteInfo(initialLocation)
+  setupLinkingAndRouteInfo(initialLocation, linking)
   subscribeToNavigationChanges()
 }
 
@@ -297,8 +299,11 @@ function cleanUpState() {
   storeSubscribers.clear()
 }
 
-function setupLinkingAndRouteInfo(initialLocation?: URL) {
-  initialState = setupLinking(routeNode, initialLocation)
+function setupLinkingAndRouteInfo(
+  initialLocation?: URL,
+  linking?: OneLinkingConfig
+) {
+  initialState = setupLinking(routeNode, initialLocation, linking)
 
   // capture the original pathname before React Navigation's linking can modify it
   initialPathname =
@@ -557,7 +562,7 @@ function getSnapshot() {
     linkTo,
     routeNode,
     rootComponent,
-    linking: getLinking(),
+    linking: getResolvedLinking(),
     hasAttemptedToHideSplash,
     initialState,
     rootState,
@@ -1059,7 +1064,7 @@ export async function linkTo(
     )
   }
 
-  const linking = getLinking()
+  const linking = getResolvedLinking()
 
   if (!linking) {
     throw new Error('Attempted to link to route when no routes are present')

package/src/router/sitemap.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { getRoutes } from './getRoutes'
+import { getSitemap } from './sitemap'
+import { getMockContext } from '../testing-utils'
+
+describe('getSitemap', () => {
+  it('maps the route tree to a public sitemap shape', () => {
+    const routes = getRoutes(
+      getMockContext([
+        '_layout.tsx',
+        'index.tsx',
+        '(app)/_layout.tsx',
+        '(app)/thread/[id].tsx',
+        'docs/[...slug].tsx',
+      ])
+    )!
+    const sitemap = getSitemap(routes)!
+
+    expect(sitemap).toMatchObject({
+      contextKey: './_layout.tsx',
+      href: '/',
+      isInternal: false,
+      isGenerated: false,
+      children: expect.arrayContaining([
+        expect.objectContaining({
+          contextKey: './index.tsx',
+          filename: 'index',
+          href: '/',
+        }),
+        expect.objectContaining({
+          contextKey: './(app)/_layout.tsx',
+          filename: '(app)/_layout',
+          href: '/(app)',
+          children: expect.arrayContaining([
+            expect.objectContaining({
+              contextKey: './(app)/thread/[id].tsx',
+              filename: 'thread/[id]',
+              href: '/(app)/thread/[id]',
+            }),
+          ]),
+        }),
+        expect.objectContaining({
+          contextKey: './docs/[...slug].tsx',
+          filename: 'docs/[...slug]',
+          href: '/docs/[...slug]',
+        }),
+      ]),
+    })
+  })
+})

package/src/router/sitemap.ts

@@ -0,0 +1,66 @@
+import { useMemo } from 'react'
+import type { OneRouter } from '../interfaces/router'
+import type { RouteNode } from './Route'
+import { removeSupportedExtensions } from './matchers'
+import { routeNode } from './router'
+import { sortRoutes } from './sortRoutes'
+
+export type SitemapType = {
+  contextKey: string
+  filename: string
+  href: string | OneRouter.Href
+  isInitial: boolean
+  isInternal: boolean
+  isGenerated: boolean
+  children: SitemapType[]
+}
+
+export function useSitemap(): SitemapType | null {
+  return useMemo(() => getSitemap(routeNode), [routeNode])
+}
+
+export function getSitemap(root: RouteNode | null): SitemapType | null {
+  return root ? mapRouteToSitemap(root, []) : null
+}
+
+function mapRouteToSitemap(route: RouteNode, parents: string[]): SitemapType {
+  return {
+    contextKey: route.contextKey,
+    filename: getRouteFilename(route),
+    href: getRouteHref(route, parents),
+    isInitial: route.initialRouteName === route.route,
+    isInternal: route.internal ?? false,
+    isGenerated: route.generated ?? false,
+    children: [...route.children]
+      .sort(sortRoutes)
+      .map((child) => mapRouteToSitemap(child, getRouteSegments(route, parents))),
+  }
+}
+
+function getRouteSegments(route: RouteNode, parents: string[]) {
+  return [...parents, ...route.route.split('/')]
+}
+
+// the sitemap exposes route patterns rather than concrete sample URLs:
+// dynamic segments stay as `[id]` / `[...slug]`, and `index` collapses to '/'.
+// callers wanting clickable links should fill in their own params.
+function getRouteHref(route: RouteNode, parents: string[]) {
+  const path = getRouteSegments(route, parents)
+    .map((segment) => (segment === 'index' ? '' : segment))
+    .filter(Boolean)
+    .join('/')
+
+  return `/${path}`
+}
+
+function getRouteFilename(route: RouteNode) {
+  const contextKey = removeSupportedExtensions(route.contextKey)
+  const segments = contextKey.split('/')
+
+  if (route.contextKey.match(/_layout\.[jt]sx?$/)) {
+    return segments.slice(-2).join('/')
+  }
+
+  const routeSegmentsCount = route.route.split('/').length
+  return segments.slice(-routeSegmentsCount).join('/')
+}

package/src/router/useInitializeOneRouter.ts

@@ -1,6 +1,7 @@
 import { useNavigationContainerRef } from '@react-navigation/native'
 import { resetLoaderState } from '../useLoader'
 import type { One } from '../vite/types'
+import type { OneLinkingConfig } from '../link/getLinking'
 import * as routerStore from './router'
 import { initialize } from './router'
 import { getSSRInitialState, ensureBaseLinkingConfig } from './linkingConfig'
@@ -15,7 +16,8 @@ let ssrRouteTreeInitialized = false
 
 export function useInitializeOneRouter(
   context: One.RouteContext,
-  initialLocation: URL | undefined
+  initialLocation: URL | undefined,
+  linking?: OneLinkingConfig
 ) {
   const navigationRef = useNavigationContainerRef()
 
@@ -23,15 +25,15 @@ export function useInitializeOneRouter(
   if (typeof window === 'undefined') {
     if (!ssrRouteTreeInitialized) {
       // first SSR request: full initialization to set up route tree, root component, etc.
-      initialize(context, navigationRef, initialLocation)
+      initialize(context, navigationRef, initialLocation, linking)
       ssrRouteTreeInitialized = true
       // also ensure linking config base is cached
-      ensureBaseLinkingConfig(routerStore.routeNode)
+      ensureBaseLinkingConfig(routerStore.routeNode, linking)
     }
 
     // per-request: compute initialState from URL (cached by path)
     const initialState = initialLocation
-      ? getSSRInitialState(routerStore.routeNode, initialLocation)
+      ? getSSRInitialState(routerStore.routeNode, initialLocation, linking)
       : routerStore.initialState
 
     // return per-request snapshot to prevent concurrent request trampling
@@ -48,7 +50,7 @@ export function useInitializeOneRouter(
     const contexts = '__react_navigation__elements_contexts'
     globalThis[contexts] = new Map<string, React.Context<any>>()
 
-    initialize(context, navigationRef, initialLocation)
+    initialize(context, navigationRef, initialLocation, linking)
     lastInitVersion = initVersion
   }
 

package/src/serve.ts

@@ -8,8 +8,29 @@ import { setupBuildInfo } from './server/setupBuildOptions'
 import { ensureExists } from './utils/ensureExists'
 import type { One } from './vite/types'
 
+// formatErrorSafely + the prepareStackTrace guard prevent a buggy transitive
+// formatter (source-map-support without recursion guard) from pinning the
+// serve process forever. see cli/install-error-handlers.ts for the full
+// story behind the 9-day Onejs:build zombies on the soot CI runner.
+import {
+  formatErrorSafely,
+  installPrepareStackTraceGuard,
+} from './cli/install-error-handlers'
+
+installPrepareStackTraceGuard()
+
 process.on('uncaughtException', (err) => {
-  console.error(`[one] Uncaught exception`, err?.stack || err)
+  try {
+    process.stderr.write(`[one serve] uncaught exception\n${formatErrorSafely(err)}\n`)
+  } catch {}
+})
+
+process.on('unhandledRejection', (reason) => {
+  try {
+    process.stderr.write(
+      `[one serve] unhandled rejection\n${formatErrorSafely(reason)}\n`,
+    )
+  } catch {}
 })
 
 export async function serve(