@nifrajs/web 3.1.0 → 3.2.0

package/src/plugins/stylex.ts

@@ -0,0 +1,298 @@
+/**
+ * StyleX integration for Nifra's Bun and Vite pipelines.
+ *
+ * The StyleX compiler stays an optional peer owned by the StyleX project. This module owns only the
+ * Nifra boundary: transform route/component modules in both pipelines, emit client CSS through the
+ * existing virtual stylesheet seam, and run the same transform without CSS for SSR.
+ */
+import type { BunPlugin } from "bun"
+import {
+  createStylesheetEmitter,
+  devServerCompile,
+  hash8,
+  normalizeFilePath,
+  reproduciblePath,
+  requirePeer,
+} from "./kit.ts"
+
+const STYLE_NS = "nifra-stylex"
+const JS_FILTER = /\.[cm]?[jt]sx?(\?|$)/
+
+/** StyleX's module resolution option, kept structural so the compiler remains an optional peer. */
+export interface StylexModuleResolution {
+  readonly type: "commonJS" | "haste"
+  readonly rootDir: string
+}
+
+/** Structural slice of `@babel/core` used by the adapter. */
+export interface StylexBabelCompiler {
+  transformAsync(
+    source: string,
+    options: Readonly<Record<string, unknown>>,
+  ): Promise<StylexBabelResult | null | undefined>
+}
+
+/** Structural slice of the StyleX Babel plugin used by the adapter. */
+export interface StylexCompiler {
+  withOptions(options: Readonly<Record<string, unknown>>): unknown
+  processStylexRules(rules: readonly unknown[], options: Readonly<Record<string, unknown>>): string
+}
+
+/** Optional peer injection and compiler configuration shared by Bun and Vite adapters. */
+export interface StylexPluginOptions {
+  /** Inject `@babel/core` in tests or advanced integrations. Defaults to the optional peer. */
+  readonly babel?: StylexBabelCompiler
+  /** Inject `@stylexjs/babel-plugin` in tests or advanced integrations. */
+  readonly compiler?: StylexCompiler
+  /** Inject Babel syntax plugins. Defaults to the three official syntax peers. */
+  readonly syntaxPlugins?: {
+    readonly flow: unknown
+    readonly jsx: unknown
+    readonly typescript: unknown
+  }
+  /** StyleX import sources to transform. Defaults to `stylex` and `@stylexjs/stylex`. */
+  readonly importSources?: readonly string[]
+  /** StyleX development transform mode. Defaults to Nifra's dev-server signal. */
+  readonly dev?: boolean
+  /** StyleX CSS layer output. Defaults to `true` for deterministic precedence. */
+  readonly useCSSLayers?: boolean
+  /** StyleX's module resolution policy. */
+  readonly unstable_moduleResolution?: StylexModuleResolution
+  /** Extra Babel plugins and presets merged before the StyleX plugin. */
+  readonly babelConfig?: {
+    readonly plugins?: readonly unknown[]
+    readonly presets?: readonly unknown[]
+  }
+}
+
+interface StylexBabelResult {
+  readonly code?: unknown
+  readonly metadata?: unknown
+}
+
+interface StylexTransformedModule {
+  readonly code: string
+  readonly css: string
+}
+
+interface StylexDependencies {
+  readonly babel: StylexBabelCompiler
+  readonly compiler: StylexCompiler
+  readonly syntax: Required<StylexPluginOptions>["syntaxPlugins"]
+}
+
+interface RecordLike {
+  readonly [key: string]: unknown
+}
+
+const isRecord = (value: unknown): value is RecordLike =>
+  (typeof value === "object" && value !== null) || typeof value === "function"
+
+const unwrapDefault = (value: unknown): unknown => {
+  if (!isRecord(value)) return value
+  return value.default ?? value
+}
+
+const isBabelCompiler = (value: unknown): value is StylexBabelCompiler =>
+  isRecord(value) && typeof value.transformAsync === "function"
+
+const isStylexCompiler = (value: unknown): value is StylexCompiler =>
+  isRecord(value) &&
+  typeof value.withOptions === "function" &&
+  typeof value.processStylexRules === "function"
+
+const syntaxPeer = async (specifier: string, feature: string): Promise<unknown> =>
+  unwrapDefault(
+    await requirePeer<unknown>(specifier, {
+      feature,
+      install: `bun add -d ${specifier}`,
+    }),
+  )
+
+const loadBabelCompiler = async (options: StylexPluginOptions): Promise<StylexBabelCompiler> => {
+  if (options.babel !== undefined) return options.babel
+  const loaded = await requirePeer<unknown>("@babel/core", {
+    feature: "StyleX compilation",
+    install: "bun add -d @babel/core",
+  })
+  const compiler = unwrapDefault(loaded)
+  if (!isBabelCompiler(compiler)) {
+    throw new Error("[nifra/web] the installed @babel/core does not expose transformAsync")
+  }
+  return compiler
+}
+
+const loadStylexCompiler = async (options: StylexPluginOptions): Promise<StylexCompiler> => {
+  if (options.compiler !== undefined) return options.compiler
+  const loaded = await requirePeer<unknown>("@stylexjs/babel-plugin", {
+    feature: "StyleX compilation",
+    install: "bun add -d @stylexjs/babel-plugin",
+  })
+  const compiler = unwrapDefault(loaded)
+  if (!isStylexCompiler(compiler)) {
+    throw new Error(
+      "[nifra/web] the installed @stylexjs/babel-plugin does not expose the StyleX compiler API",
+    )
+  }
+  return compiler
+}
+
+const loadSyntaxPlugins = async (
+  options: StylexPluginOptions,
+): Promise<Required<StylexPluginOptions>["syntaxPlugins"]> => {
+  if (options.syntaxPlugins !== undefined) return options.syntaxPlugins
+  const [flow, jsx, typescript] = await Promise.all([
+    syntaxPeer("@babel/plugin-syntax-flow", "StyleX Flow syntax parsing"),
+    syntaxPeer("@babel/plugin-syntax-jsx", "StyleX JSX syntax parsing"),
+    syntaxPeer("@babel/plugin-syntax-typescript", "StyleX TypeScript syntax parsing"),
+  ])
+  return { flow, jsx, typescript }
+}
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+const containsStylexImport = (source: string, importSources: readonly string[]): boolean =>
+  importSources.some((specifier) => {
+    const escaped = escapeRegExp(specifier)
+    return new RegExp(
+      `(?:from\\s*['"]${escaped}['"]|import\\s*\\(\\s*['"]${escaped}['"]\\s*\\)|require\\s*\\(\\s*['"]${escaped}['"]\\s*\\))`,
+      "m",
+    ).test(source)
+  })
+
+const loaderFor = (path: string): "js" | "jsx" | "ts" | "tsx" => {
+  const clean = path.split("?", 1)[0] ?? path
+  if (clean.endsWith(".tsx")) return "tsx"
+  if (clean.endsWith(".jsx")) return "jsx"
+  if (clean.endsWith(".ts") || clean.endsWith(".mts") || clean.endsWith(".cts")) return "ts"
+  return "js"
+}
+
+const moduleResolution = (options: StylexPluginOptions): StylexModuleResolution =>
+  options.unstable_moduleResolution ?? { type: "commonJS", rootDir: process.cwd() }
+
+const transformModule = async (
+  source: string,
+  filename: string,
+  options: StylexPluginOptions,
+  dependencies: Promise<StylexDependencies>,
+): Promise<StylexTransformedModule | undefined> => {
+  if (!containsStylexImport(source, options.importSources ?? ["stylex", "@stylexjs/stylex"])) {
+    return undefined
+  }
+
+  const { babel, compiler, syntax } = await dependencies
+  const result = await babel.transformAsync(source, {
+    babelrc: false,
+    filename,
+    presets: [...(options.babelConfig?.presets ?? [])],
+    plugins: [
+      ...((options.babelConfig?.plugins ?? []) as readonly unknown[]),
+      /\.jsx?$/.test(filename) ? syntax.flow : [syntax.typescript, { isTSX: true }],
+      syntax.jsx,
+      compiler.withOptions({
+        dev: options.dev ?? devServerCompile(),
+        importSources: options.importSources ?? ["stylex", "@stylexjs/stylex"],
+        treeshakeCompensation: true,
+        unstable_moduleResolution: moduleResolution(options),
+      }),
+    ],
+  })
+  const code = typeof result?.code === "string" ? result.code : undefined
+  if (code === undefined) return undefined
+
+  const metadata = isRecord(result?.metadata) ? result.metadata : undefined
+  const rules = Array.isArray(metadata?.stylex) ? metadata.stylex : []
+  const css =
+    rules.length === 0
+      ? ""
+      : compiler.processStylexRules(rules, {
+          useCSSLayers: options.useCSSLayers ?? true,
+        })
+  return { code, css }
+}
+
+const dependenciesFor = (options: StylexPluginOptions): (() => Promise<StylexDependencies>) => {
+  let dependencies: Promise<StylexDependencies> | undefined
+  return (): Promise<StylexDependencies> => {
+    dependencies ??= Promise.all([
+      loadBabelCompiler(options),
+      loadStylexCompiler(options),
+      loadSyntaxPlugins(options),
+    ]).then(([babel, compiler, syntax]) => ({ babel, compiler, syntax }))
+    return dependencies
+  }
+}
+
+/** Build a Bun plugin that transforms StyleX and emits CSS for the browser or class maps for SSR. */
+export function stylexBunPlugin(
+  generate: "dom" | "ssr",
+  options: StylexPluginOptions = {},
+): BunPlugin {
+  return {
+    name: `nifra-stylex-${generate}`,
+    setup(build) {
+      const stylesheet = generate === "dom" ? createStylesheetEmitter(build, STYLE_NS) : undefined
+      const dependencies = dependenciesFor(options)
+      build.onLoad({ filter: JS_FILTER }, async (args) => {
+        const path = normalizeFilePath(args.path)
+        const source = await Bun.file(path).text()
+        const transformed = await transformModule(source, path, options, dependencies())
+        if (transformed === undefined) return
+        const contents =
+          generate === "dom" && stylesheet !== undefined && transformed.css !== ""
+            ? `${transformed.code}\n${stylesheet.emit(path, transformed.css)}`
+            : transformed.code
+        return { contents, loader: loaderFor(path) }
+      })
+    },
+  }
+}
+
+/** Structural Vite plugin return type. Vite remains an optional peer of `@nifrajs/web`. */
+export interface StylexVitePlugin {
+  readonly name: string
+  transform(
+    source: string,
+    id: string,
+  ): Promise<{ readonly code: string; readonly map?: null } | undefined>
+  resolveId(id: string): string | undefined
+  load(id: string): string | undefined
+}
+
+/** Build a Vite plugin that maps each transformed StyleX module to a virtual CSS asset. */
+export function stylexVitePlugin(
+  generate: "dom" | "ssr",
+  options: StylexPluginOptions = {},
+): StylexVitePlugin {
+  const cssById = new Map<string, string>()
+  const dependencies = dependenciesFor(options)
+  const virtualIdFor = (id: string): string =>
+    `virtual:nifra-stylex/${hash8(reproduciblePath(normalizeFilePath(id)))}.css`
+
+  return {
+    name: `nifra-stylex-${generate}`,
+    async transform(source, id) {
+      const path = normalizeFilePath(id)
+      const transformed = await transformModule(source, path, options, dependencies())
+      if (transformed === undefined) return undefined
+      if (generate === "ssr" || transformed.css === "") return { code: transformed.code, map: null }
+      const cssId = virtualIdFor(path)
+      cssById.set(cssId, transformed.css)
+      return {
+        code: `${transformed.code}\nimport ${JSON.stringify(cssId)}`,
+        map: null,
+      }
+    },
+    resolveId(id) {
+      return cssById.has(id) ? id : undefined
+    },
+    load(id) {
+      return cssById.get(id)
+    },
+  }
+}
+
+/** Convenience alias for apps that configure only a browser Vite build. */
+export const stylexVite = (options: StylexPluginOptions = {}): StylexVitePlugin =>
+  stylexVitePlugin("dom", options)

package/src/plugins/svg.ts

@@ -16,7 +16,7 @@
  * `style="..."` into an object, and drops XML declarations/comments so the result is valid JSX.
  */
 import type { BunPlugin } from "bun"
-import { requirePeer } from "./kit.ts"
+import { normalizeFilePath, requirePeer } from "./kit.ts"
 
 /** The subset of the `svgo` API this plugin uses (structural, so no hard dependency on its types). */
 export interface SvgOptimizer {
@@ -168,7 +168,7 @@ export function svgComponentBunPlugin(
       }
 
       build.onLoad({ filter: SVG_FILTER }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         let xml = await Bun.file(path).text()
         const svgo = await getOptimizer()
         if (svgo !== undefined) {

package/src/router.ts

@@ -215,7 +215,7 @@ export interface FetcherState {
 /**
  * An independent load/submit state machine, retrieved by `router.fetcher(key)`. Runs **concurrently**
  * with the main router and with other fetchers - each is single-flight against *itself* (its own
- * monotonic token), so N row-level mutations / side-channel loads can be in flight at once without
+ * monotonic generation), so N row-level mutations / side-channel loads can be in flight at once without
  * disturbing the active view. Loads/submits write the shared cache and honor `X-Nifra-Revalidate`.
  */
 export interface Fetcher {
@@ -388,7 +388,7 @@ const defaultFetchData: FetchRouteData = async (path, _match, signal, navigation
 }
 
 /**
- * Create the agnostic router store. `navigate` is guarded by a monotonic token so that when
+ * Create the agnostic router store. `navigate` is guarded by a monotonic generation so that when
  * navigations overlap, only the latest result is applied (rapid clicks don't flash stale data).
  * A failed fetch clears `pending` and rethrows so the caller can fall back to a full-page load.
  */
@@ -581,7 +581,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     hydrated = true
     const route = { routeId: state.routeId, params: state.params }
     if (routeHooks[route.routeId]?.clientLoader === undefined) return
-    const mine = ++token
+    const mine = ++generation
     navAbort?.abort()
     const ac = new AbortController()
     navAbort = ac
@@ -597,7 +597,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       () => Promise.resolve(initial),
       initial,
     )
-    if (mine !== token) return
+    if (mine !== generation) return
     if (loaded.terminalRouteId !== undefined) {
       await loadModule?.(loaded.terminalRouteId)
       state = { ...state, routeId: loaded.terminalRouteId, params: {}, data: null }
@@ -613,7 +613,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   }
   let state = options.initial
   const listeners = new Set<() => void>()
-  let token = 0
+  let generation = 0
   // Snapshot listeners to defend against accidental un/subscribe during notification. The adapters
   // don't do this (un/subscribe runs in effect/cleanup ticks), so the overhead is negligible
   // (5-20 listeners typically), and the defensiveness is valuable.
@@ -684,10 +684,10 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
   // (so a superseded route's NDJSON stream stops reading instead of draining in the background).
   let navAbort: AbortController | undefined
 
-  // Refetch the active route + republish, single-flight via the shared `token`. Shared by `invalidate`
+  // Refetch the active route + republish, single-flight via the shared `generation`. Shared by `invalidate`
   // and targeted revalidation. Rejects if the fetch fails (clearing its own `pending` first).
   const refetchActive = async (): Promise<void> => {
-    const mine = ++token
+    const mine = ++generation
     navAbort?.abort()
     const ac = new AbortController()
     navAbort = ac
@@ -698,7 +698,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       const loaded = await applyClientLoader(state.path, active, ac.signal, () =>
         loadRouteData(state.path, active, ac.signal),
       )
-      if (mine !== token) return // superseded - drop the stale result
+      if (mine !== generation) return // superseded - drop the stale result
       cachePut(state.path, loaded)
       state = {
         ...state,
@@ -709,7 +709,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       }
       emit()
     } catch (err) {
-      if (mine === token) {
+      if (mine === generation) {
         state = { ...state, pending: false }
         emit()
       }
@@ -748,7 +748,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
 
   const createFetcher = (): FetcherEntry => {
     let fState: FetcherState = { pending: false, data: undefined }
-    let fToken = 0
+    let fGeneration = 0
     let fAbort: AbortController | undefined
     let loadedPath: string | undefined
     const fListeners = new Set<() => void>()
@@ -759,7 +759,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
     const runLoad = async (path: string): Promise<void> => {
       const matched = match(path)
       if (matched === null) return // unmatched path → no-op
-      const mine = ++fToken
+      const mine = ++fGeneration
       fAbort?.abort()
       const ac = new AbortController()
       fAbort = ac
@@ -770,7 +770,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           loadModule?.(matched.routeId),
           loadRouteData(path, matched, ac.signal),
         ])
-        if (mine !== fToken) return // a newer load/submit on THIS fetcher superseded us
+        if (mine !== fGeneration) return // a newer load/submit on THIS fetcher superseded us
         // Record the loaded path only on SUCCESS - a thrown or superseded load must not
         // leave `loadedPath` pointing at a path this fetcher never actually showed, or a later
         // `X-Nifra-Revalidate` for it would spuriously refetch onto unexpected data.
@@ -779,7 +779,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         fState = { ...fState, data: loaded.data, pending: false }
         fEmit()
       } catch (err) {
-        if (mine === fToken) {
+        if (mine === fGeneration) {
           fState = { ...fState, pending: false }
           fEmit()
         }
@@ -796,7 +796,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       },
       load: runLoad,
       submit: async (action, body) => {
-        const mine = ++fToken
+        const mine = ++fGeneration
         // Abort any prior in-flight load/submit on THIS fetcher (its fetch + NDJSON drain) - like
         // `runLoad` does for a superseding load. The mutation POST is left to complete; the
         // signal cancels the follow-up data drain if a newer op supersedes this one.
@@ -817,7 +817,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             throw new Error(`[nifra/web] fetcher action failed (${res.status}): ${action}`)
           const actionData = res.status === 204 ? undefined : await readResponseData(res, ac.signal)
           const changed = parseRevalidate(res.headers.get(REVALIDATE_HEADER))
-          if (mine !== fToken) return
+          if (mine !== fGeneration) return
           // Publish the fetcher's actionData; clear `submission` (the optimistic window is over).
           fState = { pending: false, data: fState.data, actionData }
           fEmit()
@@ -828,7 +828,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             await refreshMounted(changed, false)
           }
         } catch (err) {
-          if (mine === fToken) {
+          if (mine === fGeneration) {
             fState = { pending: false, data: fState.data }
             fEmit()
           }
@@ -872,7 +872,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           searchClientKeys[state.routeId] ?? [],
         )
       ) {
-        ++token // supersede any in-flight navigation so its late result is dropped
+        ++generation // supersede any in-flight navigation so its late result is dropped
         navAbort?.abort()
         cachePut(path, {
           data: state.data,
@@ -883,7 +883,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         emit()
         return
       }
-      const mine = ++token
+      const mine = ++generation
       navAbort?.abort() // abandon any in-flight navigation's stream
       const ac = new AbortController()
       navAbort = ac
@@ -914,7 +914,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           prefetchedData,
         )
         if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
-        if (mine !== token) return // a newer navigation superseded this one - drop the stale result
+        if (mine !== generation) return // a newer navigation superseded this one - drop the stale result
         cachePut(path, loaded) // keep the keyed cache coherent with what we publish
         const interception =
           loaded.terminalRouteId === undefined
@@ -959,7 +959,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       } catch (err) {
         // Clear our pending flag + target (only if still current) and rethrow - the caller decides how
         // to recover (the history layer falls back to a full-page navigation).
-        if (mine === token) {
+        if (mine === generation) {
           state = { ...state, pending: false, pendingPath: undefined }
           emit()
         }
@@ -967,7 +967,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       }
     },
     submit: async (action, body, opts) => {
-      const mine = ++token
+      const mine = ++generation
       const previousActionData = state.actionData
       // A superseding navigation/submit aborts this submit's FOLLOW-UP reads (revalidation / redirect
       // fetch + their NDJSON drains) - not the mutation POST itself, which should complete.
@@ -1013,7 +1013,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
             ),
           )
           if (loaded.terminalRouteId !== undefined) await loadModule?.(loaded.terminalRouteId)
-          if (mine !== token) return
+          if (mine !== generation) return
           cachePut(redirectTo, loaded)
           state = {
             routeId: loaded.terminalRouteId ?? target.routeId,
@@ -1049,7 +1049,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
           : await applyClientLoader(state.path, active, ac.signal, () =>
               loadRouteData(state.path, active, ac.signal),
             )
-        if (mine !== token) return
+        if (mine !== generation) return
         cachePut(state.path, loaded) // the revalidated (or kept) data is now the cache's truth
         // Mark the OTHER changed routes stale so the next access refetches.
         markStale(changed.filter((p) => p !== state.path))
@@ -1070,7 +1070,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         // revalidated inline above, so skip it here). Best-effort - never rejects the submit.
         await refreshMounted(changed, true)
       } catch (err) {
-        if (mine === token) {
+        if (mine === generation) {
           // Revert: clear `submission` (the optimistic view vanishes) leaving `data` untouched, so the
           // pre-submit data shows through.
           state = {

package/src/vite.ts

@@ -16,7 +16,7 @@ import {
   type IncomingMessage,
   type ServerResponse,
 } from "node:http"
-import { relative, resolve as resolvePath } from "node:path"
+import { isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
 import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { listenOrExplain } from "./dev-port.ts"
 import { discoverRoutes } from "./fs.ts"
@@ -31,7 +31,13 @@ import {
 import { vitePublicEnvPrefix } from "./internal/server-boundary.ts"
 import { importVite } from "./internal/vite-import.ts"
 import { scopedName } from "./plugins/css-modules.ts"
-import { DEV_ROOT_ENV, DEV_ROUTES_ENV, reproduciblePath } from "./plugins/kit.ts"
+import {
+  DEV_ROOT_ENV,
+  DEV_ROUTES_ENV,
+  normalizeFilePath,
+  portablePath,
+  reproduciblePath,
+} from "./plugins/kit.ts"
 import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
 import { viteServerOnlyEmpty } from "./plugins/vite-server-only.ts"
 
@@ -139,6 +145,19 @@ export { LAST_ERROR_PATH } from "./diagnostic.ts"
 // The codegen'd client entry is written here (at the Vite root) so Vite serves + HMRs it.
 const DEV_ENTRY = ".nifra-vite-entry.tsx"
 
+/** Candidate spellings for Vite's module-graph map. Vite has used native and slash-normalized
+ * absolute Windows paths across versions, while watcher events can additionally arrive as a file URL. */
+const modulePathCandidates = (path: string): string[] => {
+  const native = normalizeFilePath(path)
+  const portable = portablePath(path)
+  return [...new Set([path, native, portable])]
+}
+
+const pathInside = (root: string, path: string): boolean => {
+  const rel = relative(resolvePath(root), resolvePath(normalizeFilePath(path)))
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}
+
 const readNodeBody = async (req: IncomingMessage): Promise<Buffer | undefined> => {
   if (req.method === "GET" || req.method === "HEAD") return undefined
   const chunks: Buffer[] = []
@@ -344,7 +363,8 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   process.env[DEV_ROUTES_ENV] = routesDir
 
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
-  const toUrl = (file: string): string => `/${relative(root, `${routesDir}/${file}`)}`
+  const toUrl = (file: string): string =>
+    `/${relative(root, join(routesDir, file)).replaceAll("\\", "/")}`
   const writeClientEntry = (): void => {
     const manifest = discoverRoutes(routesDir)
     writeFileSync(
@@ -523,10 +543,13 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const invalidateImporterClosure = (path: string): void => {
     const graph = vite.moduleGraph
     if (graph === undefined) return
-    const roots = graph.getModulesByFile(path)
-    if (roots === undefined) return
     const seen = new Set<ViteModuleNode>()
-    const stack = [...roots]
+    const stack: ViteModuleNode[] = []
+    for (const candidate of modulePathCandidates(path)) {
+      const roots = graph.getModulesByFile(candidate)
+      if (roots !== undefined) stack.push(...roots)
+    }
+    if (stack.length === 0) return
     for (let mod = stack.pop(); mod !== undefined; mod = stack.pop()) {
       if (seen.has(mod)) continue
       seen.add(mod)
@@ -549,11 +572,12 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
       })
       .catch((err) => console.error("[nifra/web/vite] app re-create failed:", err))
   }
-  vite.watcher.on("change", refreshApp)
+  vite.watcher.on("change", (path) => refreshApp(normalizeFilePath(path)))
   for (const event of ["add", "unlink"] as const) {
     vite.watcher.on(event, (path) => {
-      if (path.startsWith(`${routesDir}/`) || path.startsWith(`${routesDir}\\`)) writeClientEntry()
-      refreshApp(path)
+      const filePath = normalizeFilePath(path)
+      if (pathInside(routesDir, filePath)) writeClientEntry()
+      refreshApp(filePath)
     })
   }