@nifrajs/web 4.0.0 → 5.0.0

package/src/server-components/typescript.ts

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module"
+import type * as TS from "typescript"
+
+/** The code of the error a TypeScript without the in-process compiler API raises here. */
+export const UNSUPPORTED_TYPESCRIPT = "NIFRA_TS_UNSUPPORTED"
+
+function isCompiler(value: unknown): value is typeof TS {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "createSourceFile" in value &&
+    typeof value.createSourceFile === "function"
+  )
+}
+
+/**
+ * The TypeScript compiler API, resolved from `from` the way `import "typescript"` there would be.
+ * TypeScript 7's package ships no in-process compiler API (its root export is only `version`), so
+ * it raises an error that names the fix instead of a TypeError on first use.
+ */
+export function loadTypeScript(from: string = import.meta.url): typeof TS {
+  const loaded: unknown = createRequire(from)("typescript")
+  if (isCompiler(loaded)) return loaded
+  const version =
+    typeof loaded === "object" &&
+    loaded !== null &&
+    "version" in loaded &&
+    typeof loaded.version === "string"
+      ? loaded.version
+      : "unknown"
+  throw Object.assign(
+    new Error(
+      `${UNSUPPORTED_TYPESCRIPT}: server components read component modules with the TypeScript compiler API, which TypeScript ${version} does not ship. Pin the project to TypeScript 6 (for example, \`bun add -d typescript@^6\`).`,
+    ),
+    { code: UNSUPPORTED_TYPESCRIPT, version },
+  )
+}
+
+export const ts: typeof TS = loadTypeScript()

package/src/server-components/value.ts

@@ -0,0 +1,82 @@
+import { ServerComponentError } from "./error.ts"
+import type { ComponentValue } from "./types.ts"
+
+/** Property order does not identify a resource; callers supply already-validated DTO inputs. */
+export function componentInputKey(value: ComponentValue): string {
+  if (Array.isArray(value)) return `[${value.map(componentInputKey).join(",")}]`
+  if (typeof value === "object" && value !== null)
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${componentInputKey(Reflect.get(value, key))}`)
+      .join(",")}}`
+  return JSON.stringify(value)
+}
+
+const encoder = new TextEncoder()
+const forbidden = new Set(["__proto__", "prototype", "constructor"])
+
+export function componentValue(value: unknown, maxBytes: number = 65536): ComponentValue {
+  const seen = new Set<object>()
+  let nodes = 0
+  let bytes = 0
+  const charge = (text: string): void => {
+    bytes += encoder.encode(text).byteLength
+    if (bytes > maxBytes) throw new ServerComponentError("component_limit", 413)
+  }
+  const visit = (item: unknown, depth: number): ComponentValue => {
+    if (++nodes > 8192 || depth > 16) throw new ServerComponentError("component_limit", 413)
+    if (
+      item === null ||
+      typeof item === "string" ||
+      typeof item === "boolean" ||
+      (typeof item === "number" && Number.isFinite(item))
+    ) {
+      charge(JSON.stringify(item))
+      return item
+    }
+    if (typeof item !== "object" || item === null || seen.has(item))
+      throw new ServerComponentError("component_contract")
+    const array = Array.isArray(item)
+    const prototype = Object.getPrototypeOf(item)
+    if (
+      array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null
+    ) {
+      throw new ServerComponentError("component_contract")
+    }
+    // Reject custom serializers without invoking them, including inherited serializers.
+    if ("toJSON" in item || Object.getOwnPropertySymbols(item).length > 0)
+      throw new ServerComponentError("component_contract")
+    const descriptors = Object.getOwnPropertyDescriptors(item)
+    const names = Object.keys(descriptors)
+    if (array && (item.length > 8192 || names.length !== item.length + 1))
+      throw new ServerComponentError("component_contract")
+    const result: ComponentValue[] | Record<string, ComponentValue> = array
+      ? []
+      : Object.create(null)
+    seen.add(item)
+    charge(array ? "[]" : "{}")
+    let count = 0
+    for (const name of names) {
+      if (array && name === "length") continue
+      const property = descriptors[name]!
+      if (
+        forbidden.has(name) ||
+        !property.enumerable ||
+        !Object.hasOwn(property, "value") ||
+        (array && (!/^(0|[1-9][0-9]*)$/.test(name) || Number(name) >= item.length))
+      ) {
+        throw new ServerComponentError("component_contract")
+      }
+      charge((count++ === 0 ? "" : ",") + (array ? "" : `${JSON.stringify(name)}:`))
+      Object.defineProperty(result, name, {
+        value: visit(property.value, depth + 1),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      })
+    }
+    seen.delete(item)
+    return result
+  }
+  return visit(value, 0)
+}

package/src/server-components/vite.ts

@@ -0,0 +1,242 @@
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { resolve } from "node:path"
+import type * as TS from "typescript"
+import { type Plugin, version as viteVersion } from "vite"
+import {
+  compileComponentModule,
+  componentReference,
+  directive,
+  exportedValues,
+  guardCreateElementCalls,
+  sourceFile,
+} from "./source.ts"
+import { ts } from "./typescript.ts"
+
+const componentFile = /\.component\.server\.[cm]?[jt]sx?$/
+const islandFile = /\.island\.[cm]?[jt]sx?$/
+const referencePrefix = "\0nifra-component-reference:"
+const nativeQuery = "nifra-native-client-reference"
+const reactRuntime = "\0nifra-component-react-runtime"
+// Vite uses forward slashes for module IDs even when the filesystem uses backslashes.
+const bare = (id: string): string => (id.split("?")[0] ?? id).replaceAll("\\", "/")
+
+export interface ServerComponentsPluginOptions {
+  readonly root: string
+  readonly adapter: "react" | "vue" | "svelte" | "solid" | "preact"
+}
+
+function nativeFacade(source: string, file: string): string {
+  const prefix = file.replace(/\.[cm]?[jt]sx?$/, ".props.")
+  const extensions = /\.[cm]?jsx?$/.test(file)
+    ? ["js", "mjs", "cjs", "ts"]
+    : ["ts", "mts", "cts", "js"]
+  const companion =
+    extensions.map((extension) => prefix + extension).find(existsSync) ?? prefix + extensions[0]
+  if (!existsSync(companion))
+    throw new Error(
+      `[nifra/components] ${file} requires ${companion}: export a closed props schema for every native client component`,
+    )
+  const schemas = sourceFile(readFileSync(companion, "utf8"), companion)
+  const registered = new Set(exportedValues(schemas))
+  const slots = new Map<string, readonly string[]>()
+  for (const statement of schemas.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.name.text.endsWith("Slots")) continue
+      let value = declaration.initializer
+      if (value !== undefined && ts.isAsExpression(value)) value = value.expression
+      if (
+        value === undefined ||
+        !ts.isArrayLiteralExpression(value) ||
+        !value.elements.every(ts.isStringLiteral)
+      )
+        throw new Error("[nifra/components] Managed slot names must be a literal array")
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The compiler inspects trusted AST/package metadata and its own populated stub map; application data never supplies these values.
+      const names = value.elements.map((node) => (node as TS.StringLiteral).text)
+      if (
+        names.some(
+          (name) =>
+            !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name) ||
+            name === "ref" ||
+            name === "key" ||
+            name === "constructor",
+        )
+      )
+        throw new Error("[nifra/components] Invalid managed slot name")
+      slots.set(declaration.name.text.slice(0, -5), names)
+    }
+  }
+  const names = exportedValues(sourceFile(source, file))
+  const exports = names.map((name, index) => {
+    if (!registered.has(name))
+      throw new Error(
+        `[nifra/components] Native client export ${name} in ${file} has no registered props schema`,
+      )
+    if (name !== "default" && !/^[$A-Z_a-z][$\w]*$/.test(name))
+      throw new Error("[nifra/components] Native client export names must be identifiers")
+    const local = `__nifra_client_${index}`
+    const value = `__guard(__native[${JSON.stringify(name)}], __schemas[${JSON.stringify(name)}], ${JSON.stringify(slots.get(name) ?? [])})`
+    return name === "default"
+      ? `const ${local} = ${value}; export default ${local};`
+      : `export const ${name} = ${value};`
+  })
+  return [
+    'import { guardedClientReference as __guard } from "@nifrajs/web-react/server-components/guard";',
+    `import * as __native from ${JSON.stringify(`${file}?${nativeQuery}`)};`,
+    `import * as __schemas from ${JSON.stringify(companion)};`,
+    ...exports,
+  ].join("\n")
+}
+
+/** Compiler bridge. The ordinary build must continue rejecting arbitrary server imports. */
+export function serverComponentsPlugin(
+  options: ServerComponentsPluginOptions,
+): Plugin & { readonly api: { readonly componentModules: ReadonlySet<string> } } {
+  const stubs = new Map<string, string>()
+  const internal = new Set<string>()
+  const nativeReferences = new Set<string>()
+  const componentModules = new Set<string>()
+  return {
+    api: { componentModules },
+    name: "nifra:server-components",
+    enforce: "pre",
+    configResolved(config) {
+      if (viteVersion !== "8.2.1")
+        throw new Error(
+          "[nifra/components] Use the certified Vite 8.2.1 component pipeline; Bun remains a supported server runtime",
+        )
+      if (options.adapter === "react") {
+        const require = createRequire(resolve(config.root, "package.json"))
+        const versions = ["react", "react-dom", "react-server-dom-webpack"].map((name) => {
+          try {
+            // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The compiler inspects trusted AST/package metadata and its own populated stub map; application data never supplies these values.
+            return (require(`${name}/package.json`) as { version: string }).version
+          } catch {
+            throw new Error(
+              `[nifra/components] Install ${name}@19.2.8 for the React component pipeline`,
+            )
+          }
+        })
+        if (versions.some((version) => version !== "19.2.8"))
+          throw new Error(
+            "[nifra/components] React, React DOM, and Flight must all use the matching 19.2.8 version",
+          )
+      }
+    },
+    async resolveId(source, importer) {
+      const environment = this.environment.name
+      if (source === "react" && environment === "rsc" && !internal.has(bare(importer ?? ""))) {
+        internal.add(reactRuntime)
+        const guard = await this.resolve("@nifrajs/web-react/server-components/guard", importer, {
+          skipSelf: true,
+        })
+        if (guard !== null) internal.add(bare(guard.id))
+        return reactRuntime
+      }
+      if (source.startsWith("\0virtual:vite-rsc/") && environment !== "rsc") return null
+      if (source.startsWith("@nifrajs/web-react/server-components/")) {
+        const resolved = await this.resolve(source, importer, { skipSelf: true })
+        if (resolved !== null) internal.add(bare(resolved.id))
+        return resolved
+      }
+      if (source.includes(nativeQuery)) {
+        const file = source.startsWith("/@fs/")
+          ? source.slice("/@fs".length).replace(/^\/(?=[A-Za-z]:[\\/])/, "")
+          : existsSync(bare(source))
+            ? source
+            : resolve(options.root, `.${source}`)
+        if (
+          !nativeReferences.has(bare(file)) ||
+          (environment === "rsc" && (importer === undefined || bare(importer) !== bare(file)))
+        )
+          throw new Error(
+            "[nifra/components] Raw native client references are compiler-owned; import the registered client component",
+          )
+        return file
+      }
+      if (source.startsWith(referencePrefix) || source.startsWith("\0")) return null
+      if (
+        environment === "rsc" &&
+        options.adapter === "react" &&
+        (source === "react/jsx-runtime" || source === "react/jsx-dev-runtime") &&
+        !internal.has(bare(importer ?? ""))
+      ) {
+        const resolved = await this.resolve(
+          `@nifrajs/web-react/server-components/${source.endsWith("dev-runtime") ? "jsx-dev-runtime" : "jsx-runtime"}`,
+          importer,
+          { skipSelf: true },
+        )
+        if (resolved === null)
+          throw new Error("[nifra/components] Install the matching @nifrajs/web-react adapter")
+        internal.add(bare(resolved.id))
+        const guard = await this.resolve("@nifrajs/web-react/server-components/guard", importer, {
+          skipSelf: true,
+        })
+        if (guard !== null) internal.add(bare(guard.id))
+        return resolved
+      }
+      if (environment !== "client") return null
+      const resolved = await this.resolve(source, importer, { skipSelf: true })
+      if (resolved === null || !componentFile.test(bare(resolved.id))) return null
+      if (resolved.id !== bare(resolved.id))
+        throw new Error("[nifra/components] Server component source cannot be imported as an asset")
+      const compiled = compileComponentModule(
+        readFileSync(resolved.id, "utf8"),
+        resolved.id,
+        options.root,
+        "client",
+      )
+      const id = referencePrefix + componentReference(resolved.id, options.root, "module")
+      stubs.set(id, compiled.code)
+      return id
+    },
+    load(id) {
+      if (id === reactRuntime)
+        return {
+          code: 'import * as Native from "react"; import { guardedCreateElement as createElement, guardedCloneElement as cloneElement } from "@nifrajs/web-react/server-components/guard"; export { Children, Fragment, Profiler, StrictMode, Suspense, __SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, cache, cacheSignal, captureOwnerStack, createRef, forwardRef, isValidElement, lazy, memo, use, useCallback, useDebugValue, useId, useMemo, version } from "react"; export { createElement, cloneElement }; export default { ...Native, createElement, cloneElement };',
+          map: null,
+        }
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The compiler inspects trusted AST/package metadata and its own populated stub map; application data never supplies these values.
+      if (stubs.has(id)) return { code: stubs.get(id) as string, map: null }
+      const path = bare(id)
+      if (id.endsWith(`?${nativeQuery}`)) return { code: readFileSync(path, "utf8"), map: null }
+      if (!/\.[cm]?[jt]sx?$/.test(path) || !existsSync(path)) return null
+      const source = readFileSync(path, "utf8")
+      const ast = sourceFile(source, path)
+      if (directive(ast, "use server"))
+        throw new Error(
+          `[nifra/components] Native use-server actions in ${path} are unsupported; use a validated serverFn in a *.fn.ts module`,
+        )
+      if (
+        this.environment.name === "rsc" &&
+        options.adapter === "react" &&
+        directive(ast, "use client")
+      ) {
+        nativeReferences.add(path)
+        return { code: nativeFacade(source, path), map: null }
+      }
+      return null
+    },
+    transform(source, id) {
+      if (id.includes(nativeQuery) || internal.has(bare(id))) return null
+      const path = bare(id)
+      let code = source
+      if (componentFile.test(path)) {
+        code = compileComponentModule(source, path, options.root, this.environment.name).code
+        componentModules.add(path)
+      }
+      if (islandFile.test(path))
+        code = compileComponentModule(
+          source,
+          path,
+          options.root,
+          this.environment.name,
+          "island",
+        ).code
+      if (this.environment.name === "rsc" && options.adapter === "react")
+        code = guardCreateElementCalls(code, path)
+      return code === source ? null : { code, map: null }
+    },
+  }
+}

package/src/server-components.ts

@@ -0,0 +1,32 @@
+export {
+  defineServerComponent,
+  inheritOwnerAuthorization,
+  isServerComponent,
+  prepareServerComponent,
+} from "./server-components/definition.ts"
+export { type ComponentErrorCode, ServerComponentError } from "./server-components/error.ts"
+export {
+  createServerComponents,
+  defineComponentOwner,
+  type ServerComponentsOptions,
+  serverComponentIdentity,
+  serverComponentInstance,
+} from "./server-components/runtime.ts"
+export type {
+  ComponentInstance,
+  ComponentIsland,
+  ComponentKey,
+  ComponentOwner,
+  ComponentRecord,
+  ComponentRender,
+  ComponentRenderContext,
+  ComponentState,
+  ComponentValue,
+  PreparedServerComponent,
+  ServerComponent,
+  ServerComponentContext,
+  ServerComponentDefinition,
+  ServerComponentHandle,
+  ServerComponentRenderAdapter,
+  ServerComponentRuntime,
+} from "./server-components/types.ts"

package/src/service-worker.ts

@@ -13,6 +13,10 @@
  *   - **GET, same-origin, `ok`, and not `no-store`.** Anything else goes straight to the network.
  *   - **The cache name carries the build id.** A deploy that changed the assets gets a new cache, and
  *     activation deletes every older one, so a stale worker cannot pin an old build indefinitely.
+ *     Only caches named `<cacheName>:<buildId>` are the worker's: the origin's other caches - another
+ *     app's, or data the page stored itself - are never read, written or deleted.
+ *   - **Only this build's precached URLs are answered.** Every other request, an API call included,
+ *     goes to the network untouched.
  *
  * It is opt-in and generated at build time; an app that does not call this ships nothing.
  */
@@ -36,7 +40,10 @@ export interface ServiceWorkerOptions {
    * bytes. Omit it and failed navigations simply fail, which is the honest default.
    */
   readonly offlineUrl?: string
-  /** Cache name prefix. Default `nifra`. */
+  /**
+   * Cache name prefix, and the namespace activation cleans: every cache named `<cacheName>:<id>` other
+   * than this build's is deleted. Give each worker sharing an origin its own. Default `nifra`.
+   */
   readonly cacheName?: string
   /** Extra same-origin URLs to precache. Only pass immutable ones. */
   readonly additionalPrecache?: readonly string[]
@@ -101,8 +108,11 @@ export function generateServiceWorker(
   const urls = [...new Set(offline === undefined ? precache : [...precache, offline])].sort()
 
   return `// Generated by @nifrajs/web/service-worker. Do not edit.
-const CACHE = ${JSON.stringify(`${prefix}-${options.buildId}`)}
+const OWNED = ${JSON.stringify(`${prefix}:`)}
+const CACHE = OWNED + ${JSON.stringify(options.buildId)}
 const PRECACHE = ${JSON.stringify(urls)}
+const OWN_URLS = new Set(PRECACHE)
+const OWN = { cacheName: CACHE }
 const OFFLINE = ${offline === undefined ? "null" : JSON.stringify(offline)}
 
 self.addEventListener("install", (event) => {
@@ -115,7 +125,9 @@ self.addEventListener("activate", (event) => {
   event.waitUntil(
     caches
       .keys()
-      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
+      // Neither the prefix nor a build id can hold a colon, so the first one ends the namespace.
+      .then((keys) => keys.filter((k) => k !== CACHE && k.startsWith(OWNED)))
+      .then((old) => Promise.all(old.map((k) => caches.delete(k))))
       .then(() => self.clients.claim()),
   )
 })
@@ -130,20 +142,25 @@ self.addEventListener("fetch", (event) => {
   // how one user gets served the page rendered for another, so nothing is stored here.
   if (request.mode === "navigate") {
     if (OFFLINE === null) return
-    event.respondWith(fetch(request).catch(() => caches.match(OFFLINE).then((r) => r ?? Response.error())))
+    event.respondWith(
+      fetch(request).catch(() => caches.match(OFFLINE, OWN).then((r) => r ?? Response.error())),
+    )
     return
   }
 
-  // Assets: cache first, because every precached URL is content-hashed and therefore immutable.
+  // Assets: cache first, because every precached URL is content-hashed and therefore immutable. Only
+  // this build's URLs are answered, and only from this build's cache: every other request, an API
+  // call included, goes to the network, and another cache on the origin is never read.
+  if (!OWN_URLS.has(url.pathname)) return
   event.respondWith(
-    caches.match(request).then((hit) => {
+    caches.match(request, OWN).then((hit) => {
       if (hit !== undefined) return hit
       return fetch(request).then((response) => {
         const cacheable =
           response.ok &&
           response.type === "basic" &&
           !(response.headers.get("cache-control") ?? "").includes("no-store")
-        if (cacheable && PRECACHE.includes(url.pathname)) {
+        if (cacheable) {
           const copy = response.clone()
           void caches.open(CACHE).then((c) => c.put(request, copy))
         }

package/src/vite.ts

@@ -10,13 +10,15 @@
  * injects its HMR client + the framework's refresh preamble. Node `http` (not `Bun.serve`) because
  * Vite's `middlewares` are Connect-style - it runs fine under Bun.
  */
-import { writeFileSync } from "node:fs"
+
+import { type Dirent, readdirSync, writeFileSync } from "node:fs"
 import {
   createServer as createHttpServer,
   type IncomingMessage,
   type ServerResponse,
 } from "node:http"
 import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
+import { singleCopyPackageNames } from "@nifrajs/core/single-copy"
 import { CLIENT_BATCH_MAX_BYTES } from "./dev-client.ts"
 import { DEV_REQUEST_ID_HEADER, DEV_SERVER_FILES } from "./dev-feed.ts"
 import { listenOrExplain } from "./dev-port.ts"
@@ -170,6 +172,7 @@ 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"
 const VITE_CLOSE_BOUND_MS = 2000
+const POLL_INTERVAL_MS = 80
 
 /** 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. */
@@ -184,6 +187,22 @@ const pathInside = (root: string, path: string): boolean => {
   return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
 }
 
+/** Every file below `dir` as an absolute path. A directory removed mid-walk contributes nothing. */
+const filesUnder = (dir: string, into = new Set<string>()): Set<string> => {
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return into
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) filesUnder(path, into)
+    else into.add(path)
+  }
+  return into
+}
+
 const readNodeBody = async (req: IncomingMessage): Promise<Buffer | undefined> => {
   if (req.method === "GET" || req.method === "HEAD") return undefined
   const chunks: Buffer[] = []
@@ -415,6 +434,9 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
       generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
     )
   }
+  const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
+  // Listed before the entry is generated, so a file added in between is reconciled again, not lost.
+  const routeFiles = usePolling ? filesUnder(routesDir) : new Set<string>()
   writeClientEntry()
   const entryUrl = `/${DEV_ENTRY}`
 
@@ -578,7 +600,6 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   // path-shaped `clientModule` (tests) names no package; there is then nothing to externalize.
   const adapterPackage = packageNameOf(options.clientModule)
   const ssrExternal = [...(adapterPackage !== undefined ? [adapterPackage] : []), "@nifrajs/web"]
-  const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
   // The feed writes its record and log under `.nifra/`: watching them would turn every log flush into
   // a "file change" that re-creates the app and marks every entry stale.
   const watch: { ignored: RegExp[]; usePolling?: boolean; interval?: number } = {
@@ -587,7 +608,7 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   // Poll when native fs events aren't delivered (containers/sandboxes).
   if (usePolling) {
     watch.usePolling = true
-    watch.interval = 80
+    watch.interval = POLL_INTERVAL_MS
   }
   // Never `import("vite")` directly here: the guard in `importVite` has to run first, and the dev
   // server importing vite unguarded is precisely what poisoned the module for the whole process.
@@ -613,6 +634,10 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     // Ahead of the user's plugins: the zone guard refuses backend code before anything serves or
     // transforms it, and a `*.fn` module must be replaced before anything else reads it.
     plugins: [zoneGuard, viteServerFnStub(), ...plugins],
+    // Vite pre-bundles what it finds by crawling `index.html`, and this app has none: every dependency
+    // would be found mid-session instead, each one re-optimizing and reloading the page. The client
+    // entry imports every route's frontend module, so crawling it covers the whole route graph.
+    optimizeDeps: { entries: [DEV_ENTRY] },
     resolve: {
       conditions: resolveConditions,
       // Dedupe each framework runtime to ONE copy. In a multi-root workspace a shared package can pull
@@ -621,7 +646,8 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
       // on any hook-using route (the error points at the component, not the resolution - brutal to
       // diagnose). Same policy table the production builds read, so dev matches prod. No-op per
       // framework the app does not use (the package simply isn't present to dedupe).
-      dedupe: [...viteDedupePackages()],
+      // The app's single-copy declaration pins its packages the same way.
+      dedupe: [...viteDedupePackages(), ...singleCopyPackageNames(root)],
     },
     ssr: {
       // Explicit listing forces external even for workspace-LINKED packages (Vite's default keeps
@@ -722,20 +748,43 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     session.markChange()
     refreshApp(normalizeFilePath(path))
   })
+  const onAddUnlink = (event: "add" | "unlink", path: string): void => {
+    const filePath = normalizeFilePath(path)
+    const inRoutes = pathInside(routesDir, filePath)
+    if (inRoutes && usePolling) {
+      const file = resolvePath(filePath)
+      // Whichever of the watcher and the rescan below reports a route file first handles it.
+      if (routeFiles.has(file) === (event === "add")) return
+      if (event === "add") routeFiles.add(file)
+      else routeFiles.delete(file)
+    }
+    session.markChange()
+    if (inRoutes) {
+      writeClientEntry()
+      // A newly added route is not in Vite's module graph yet, so invalidating only the
+      // route path cannot evict the cached generated entry that imports the route. Evict the
+      // generated entry after rewriting it before recreating the SSR app; this also prevents
+      // an unlink refresh from briefly loading an entry that still references the deleted file.
+      invalidateImporterClosure(resolvePath(root, DEV_ENTRY))
+    }
+    refreshApp(filePath)
+  }
   for (const event of ["add", "unlink"] as const) {
-    vite.watcher.on(event, (path) => {
-      session.markChange()
-      const filePath = normalizeFilePath(path)
-      if (pathInside(routesDir, filePath)) {
-        writeClientEntry()
-        // A newly added route is not in Vite's module graph yet, so invalidating only the
-        // route path cannot evict the cached generated entry that imports the route. Evict the
-        // generated entry after rewriting it before recreating the SSR app; this also prevents
-        // an unlink refresh from briefly loading an entry that still references the deleted file.
-        invalidateImporterClosure(resolvePath(root, DEV_ENTRY))
-      }
-      refreshApp(filePath)
-    })
+    vite.watcher.on(event, (path) => onAddUnlink(event, path))
+  }
+  // Chokidar reports ready before the poller has taken its baseline stat of a directory (Bun's
+  // fs.watchFile takes it asynchronously), and a route added or removed in that gap is folded into the
+  // baseline and never reported. The manifest comes from a directory scan, so a scan diffed against the
+  // route files already handled recovers those events.
+  const reconcileRouteFiles = (): void => {
+    const onDisk = filesUnder(routesDir)
+    try {
+      for (const file of onDisk) if (!routeFiles.has(file)) onAddUnlink("add", file)
+      for (const file of [...routeFiles]) if (!onDisk.has(file)) onAddUnlink("unlink", file)
+    } catch (err) {
+      console.error("[nifra/web/vite] route rescan failed:", err)
+      session.buildFailed(err, "route rescan failed")
+    }
   }
   await watcherReady
 
@@ -756,9 +805,11 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   const address = server.address()
   const boundPort = typeof address === "object" && address !== null ? address.port : port
   session.listening(boundPort)
+  const routeRescan = usePolling ? setInterval(reconcileRouteFiles, POLL_INTERVAL_MS) : undefined
   return {
     port: boundPort,
     stop: async () => {
+      clearInterval(routeRescan)
       session.stop()
       // Cleared with the server that owns it: the slot is process-global, so a stopped server leaving
       // its loader behind would hand the next one's adapter a graph that is closed (tests start and