@nifrajs/web 2.9.1 → 2.11.0

package/src/dev-ssr-graph.ts

@@ -0,0 +1,311 @@
+/**
+ * Per-module SSR invalidation for the **Bun pipeline's** dev server.
+ *
+ * Bun's runtime caches every module it has evaluated, and nothing invalidates that cache on a file
+ * change. The dev server's answer used to stop at the route module: `discoverRoutes({ importQuery })`
+ * appends a changing query to each route's own dynamic import, so the route re-evaluates. Its imports
+ * do not - a component, a helper, a `*.server` module all keep resolving to the same cached specifier,
+ * so SSR kept rendering the code that was on disk when the server started while the client, which Bun
+ * rebuilds properly, rendered the edit. Every framework on this pipeline had it; the Vite pipeline does
+ * not, because Vite owns its own SSR module graph.
+ *
+ * The fix is that module graph, in the small: watch what the server actually imported, notice which
+ * files changed, and give exactly those - and everything that imports them - a fresh cache key.
+ *
+ * ## Why a version per module, and why version 0 means no query
+ *
+ * A cache key is a `?v=<n>` query on the resolved absolute path. Bun treats a distinct query as a
+ * distinct registry entry and re-reads the file from disk (nifra's own Bun plugins already tolerate the
+ * suffix - see the `(\?|$)` in their filters), so a bump is a reload of that module and nothing else.
+ *
+ * That "nothing else" is the reason versions start at 0 and 0 rewrites nothing at all. A module that has
+ * never been edited keeps its bare path, which is the same registry entry the CLI already loaded when it
+ * read the app's config and backend - so a database client, a queue handle, any module-scope singleton
+ * shared between the backend and a route stays ONE instance. Versioning everything up front would have
+ * forked those on the first request. Editing such a module does fork it, deliberately: the routes get
+ * the new code and the already-running backend keeps the old, which is the same deal every dev server
+ * makes, and the same one a restart resolves.
+ *
+ * ## Why importers have to be bumped too
+ *
+ * Re-evaluating a module re-runs its imports through resolution, but a module that is NOT re-evaluated
+ * never re-resolves anything. With `route -> Layout -> Button` and an edit to `Button`, the route
+ * re-evaluates (its own query moved), asks for `Layout` under the key it always used, and gets the
+ * cached `Layout` back - which never mentions `Button` again. So a change propagates UP: the edited file
+ * and every transitive importer of it are bumped together, and the chain re-evaluates from the route
+ * down.
+ *
+ * ## Why the key is written into the source, not returned from `onResolve`
+ *
+ * Rewriting a resolution is the obvious mechanism and it only covers half of the imports people write.
+ * Bun's runtime consults resolver plugins for a specifier that carries a file extension
+ * (`"./Counter.tsx"`) and not for one that does not (`"./Counter"`, `"./components"`) - the extensionless
+ * form is resolved on an internal fast path that no plugin, in any namespace, is offered. Measured on
+ * Bun 1.3.14; the bundler has no such gap. Since extensionless is how most of this ecosystem's code is
+ * written, an `onResolve`-only fix would have silently covered a minority of real apps.
+ *
+ * So the version is applied one level earlier, in the importer's own source: on load, each app-owned
+ * module has its relative specifiers rewritten to absolute paths carrying the current version of the
+ * file they point at. `onResolve` stays as well, because it is the only hook that sees modules loaded by
+ * a third-party plugin this one does not wrap.
+ *
+ * Old versions stay in Bun's registry - a bounded dev-only leak, one entry per edit, which is what the
+ * route-level query already did.
+ *
+ * Bun-only + dev-only; never imported by the edge runtime or by a production build.
+ */
+import { statSync } from "node:fs"
+import { dirname } from "node:path"
+import type { BunPlugin } from "bun"
+
+/**
+ * Extensions worth a version. Source and data only: an asset (`.css`, `.svg`, an image) either has no
+ * server-side meaning or, like CSS Modules, compiles to a pure function of its path, so re-reading it
+ * would change nothing about the rendered HTML.
+ */
+const VERSIONED = /\.(?:mts|cts|mjs|cjs|tsx|jsx|ts|js|svelte|vue|mdx|md|json)$/
+
+/** Source this module can load and rewrite itself, when no framework plugin claims the file first. */
+const REWRITABLE = "mts|cts|mjs|cjs|tsx|jsx|ts|js"
+
+/**
+ * The `onLoad` filter, which has to do the whole job of selecting app source: a **runtime** `onLoad`
+ * handler may not decline a file it was offered (Bun raises `onLoad() expects an object returned`), so
+ * anything this matches is loaded here - and a dependency's `.js` loaded as ESM when the package meant
+ * CJS would break the app. Hence the shape: under the app root, no `node_modules` segment at any depth,
+ * no dot-directory (`.nifra-bun/`, `.git/`), and a source extension, with an optional cache-busting
+ * query. It mirrors {@link SsrGraph}'s ownership test; keep the two in step.
+ */
+const appSourceFilter = (root: string): RegExp =>
+  new RegExp(
+    `^${root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/` +
+      `(?!.*/node_modules/)(?!\\.)(?!.*/\\.)[^?]*\\.(?:${REWRITABLE})(?:\\?|$)`,
+  )
+
+/**
+ * `from "x"`, `import "x"`, `import("x")`, `require("x")` - every form that carries a static specifier,
+ * including `export ... from`. What it matches is only a candidate: a hit counts as an import only if the
+ * transpiler's own scan reported the same specifier, which is what keeps a lookalike string literal out.
+ */
+const SPECIFIER = /\b(from|import|require)(\s*\(?\s*)(["'])([^"'\n]+)\3/g
+
+export interface SsrGraphOptions {
+  /** The app root. Only files under it (and outside `node_modules`) are tracked. */
+  readonly root: string
+}
+
+export interface SsrGraph {
+  /**
+   * The Bun **runtime** plugin that records the graph and re-keys imports. Register it before the first
+   * route module is imported; a runtime plugin only affects modules loaded after it.
+   */
+  readonly plugin: BunPlugin
+  /**
+   * Re-stat every tracked module and bump the versions of the changed ones and their importers.
+   * Returns `true` when anything moved, i.e. when the app has to be rebuilt.
+   */
+  sweep(): boolean
+  /** Bumped by each {@link sweep} that found a change. Belongs in the key the built app is cached under. */
+  generation(): number
+  /** Release the process-wide hook {@link rewriteSsrImports} reads. */
+  dispose(): void
+}
+
+/** `/abs/path.ts?v=2` and `file:///abs/path.ts` both name `/abs/path.ts`. */
+function plainPath(path: string): string {
+  const withoutQuery = path.split("?")[0] ?? path
+  return withoutQuery.startsWith("file://")
+    ? decodeURIComponent(withoutQuery.slice("file://".length))
+    : withoutQuery
+}
+
+const mtimeOf = (path: string): number =>
+  statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? Number.NaN
+
+/** What Bun should compile a file this module loaded itself as - the file's own extension decides. */
+const loaderFor = (path: string): "tsx" | "ts" | "jsx" | "js" =>
+  path.endsWith(".tsx")
+    ? "tsx"
+    : path.endsWith(".jsx")
+      ? "jsx"
+      : /\.[cm]?ts$/.test(path)
+        ? "ts"
+        : "js"
+
+/**
+ * What to PARSE a module as when scanning it for imports. `ts` is the safe default even for plain JS and
+ * for a plugin's compiled output (TS ⊃ JS), and the one thing it cannot also parse is JSX - which is why
+ * the JSX extensions are called out. Nothing here is emitted; the scan only reads specifiers.
+ */
+const scanLoaderFor = (path: string): "tsx" | "ts" =>
+  path.endsWith(".tsx") || path.endsWith(".jsx") ? "tsx" : "ts"
+
+/**
+ * The active graph, for the framework plugins that own a file extension this module cannot load itself
+ * (`.vue`, `.svelte`, `.tsx` under Solid, `.mdx`). Only one dev server runs per process.
+ */
+let active: { rewrite(contents: string, path: string): string } | undefined
+
+/**
+ * Re-key the app-owned imports of a module a **server-side** plugin just compiled. A plugin that claims a
+ * file extension is the only code that sees that file's source, so it is the only place its imports can
+ * be versioned; without this call every component in that language stays on the code it had at startup.
+ *
+ * A no-op outside a Bun dev server, and on the client half of a plugin - the client is bundled, and a
+ * bundle has no import cache to bust.
+ */
+export function rewriteSsrImports(contents: string, path: string, generate: "dom" | "ssr"): string {
+  if (generate !== "ssr" || active === undefined) return contents
+  return active.rewrite(contents, plainPath(path))
+}
+
+/** Track and version the app's own server-side module graph. See the module doc for the whole design. */
+export function createSsrGraph(options: SsrGraphOptions): SsrGraph {
+  const root = options.root.endsWith("/") ? options.root.slice(0, -1) : options.root
+  const prefix = `${root}/`
+  /** Every tracked module, by absolute path: its current cache version and the mtime it was read at. */
+  const nodes = new Map<string, { version: number; mtime: number }>()
+  /** Reverse edges - who imports this file - which is the direction invalidation travels. */
+  const importers = new Map<string, Set<string>>()
+  let generation = 0
+
+  /** Inside the app, outside `node_modules`, outside dot-directories, and a file worth re-reading. */
+  const owned = (abs: string): boolean => {
+    if (!abs.startsWith(prefix)) return false
+    if (abs.includes("/node_modules/")) return false
+    // Relative to the app, so a project that itself lives under a dotted directory is not excluded
+    // wholesale - this is about the app's own generated trees (`.nifra/`, `.nifra-bun/`, `.git/`).
+    const rel = abs.slice(prefix.length)
+    if (rel.startsWith(".") || rel.includes("/.")) return false
+    return VERSIONED.test(abs)
+  }
+
+  const track = (abs: string, importer: string): void => {
+    if (!nodes.has(abs)) nodes.set(abs, { version: 0, mtime: mtimeOf(abs) })
+    const parents = importers.get(abs)
+    if (parents === undefined) importers.set(abs, new Set([importer]))
+    else parents.add(importer)
+  }
+
+  // `Bun.resolveSync` re-enters this plugin's own `onResolve`, which is an unbounded recursion rather
+  // than a slow path. The flag is safe because the handler and `resolveSync` are both synchronous.
+  let resolving = false
+
+  const resolveFrom = (specifier: string, dir: string): string | undefined => {
+    resolving = true
+    try {
+      return Bun.resolveSync(specifier, dir)
+    } catch {
+      // Unresolvable here is not this module's error to report - leave it to Bun, which raises the
+      // diagnostic the app author can act on.
+      return undefined
+    } finally {
+      resolving = false
+    }
+  }
+
+  /**
+   * Record `specifier` as an edge out of `importer` and return what it should be imported as, or
+   * `undefined` to leave the specifier exactly as the author wrote it.
+   */
+  const keyFor = (specifier: string, importer: string): string | undefined => {
+    const abs = resolveFrom(specifier, dirname(importer))
+    if (abs === undefined || !owned(abs)) return undefined
+    track(abs, importer)
+    const version = nodes.get(abs)?.version ?? 0
+    // Version 0 is the shared, unversioned instance - see the module doc.
+    return version === 0 ? undefined : `${abs}?v=${version}`
+  }
+
+  const rewrite = (contents: string, importer: string): string => {
+    if (!importer.startsWith(prefix) || importer.includes("/node_modules/")) return contents
+    let scanned: readonly { readonly path: string }[]
+    try {
+      scanned = new Bun.Transpiler({ loader: scanLoaderFor(importer) }).scanImports(contents)
+    } catch {
+      // Source Bun cannot parse is source Bun is about to reject with a real error message. Hand it
+      // through untouched rather than adding a second, worse one.
+      return contents
+    }
+    const candidates = new Set(scanned.map((entry) => entry.path).filter((p) => p.startsWith(".")))
+    if (candidates.size === 0) return contents
+    const keys = new Map<string, string>()
+    for (const specifier of candidates) {
+      const key = keyFor(specifier, importer)
+      if (key !== undefined) keys.set(specifier, key)
+    }
+    if (keys.size === 0) return contents
+    // Same length in lines and columns up to the specifier itself, so a stack trace still points at the
+    // line the author wrote.
+    return contents.replace(SPECIFIER, (whole, keyword, gap, quote, specifier) =>
+      keys.has(specifier) ? `${keyword}${gap}${quote}${keys.get(specifier)}${quote}` : whole,
+    )
+  }
+
+  const plugin: BunPlugin = {
+    name: "nifra-dev-ssr-graph",
+    setup(build) {
+      // Every app-owned module that no other plugin claims: read it, re-key its imports, hand it back.
+      // Loading it here is what makes the extensionless specifiers reachable at all (module doc).
+      build.onLoad({ filter: appSourceFilter(root) }, async (args) => {
+        const path = plainPath(args.path)
+        const contents = await Bun.file(path).text()
+        return { contents: rewrite(contents, path), loader: loaderFor(path) }
+      })
+      // The resolver half covers what the loader half cannot see: a module compiled by a plugin that
+      // does not call `rewriteSsrImports`. Extension-bearing specifiers only, which is all Bun offers.
+      build.onResolve({ filter: /^[./]/ }, (args) => {
+        if (resolving) return undefined
+        // A specifier that already carries a query is either this module's own rewrite or a plugin's
+        // virtual sub-request (`?vue-css` and friends) - both are already keyed.
+        if (args.path.includes("?")) return undefined
+        const importer = plainPath(args.importer)
+        if (!importer.startsWith(prefix) || importer.includes("/node_modules/")) return undefined
+        const key = keyFor(args.path, importer)
+        return key === undefined ? undefined : { path: key }
+      })
+    },
+  }
+
+  const sweep = (): boolean => {
+    const dirty = new Set<string>()
+    for (const [abs, node] of nodes) {
+      const mtime = mtimeOf(abs)
+      // NaN (deleted, or unreadable mid-save) never equals the recorded value, so it counts as changed
+      // and the next successful stat settles it.
+      if (mtime === node.mtime) continue
+      node.mtime = mtime
+      dirty.add(abs)
+    }
+    if (dirty.size === 0) return false
+    // Breadth-first up the reverse edges: an importer of a changed module is itself stale, because it
+    // holds the old binding and would not re-resolve on its own.
+    const queue = [...dirty]
+    for (let i = 0; i < queue.length; i++) {
+      const child = queue[i]
+      if (child === undefined) continue
+      for (const parent of importers.get(child) ?? []) {
+        if (dirty.has(parent)) continue
+        dirty.add(parent)
+        queue.push(parent)
+      }
+    }
+    for (const abs of dirty) {
+      const node = nodes.get(abs)
+      if (node !== undefined) node.version += 1
+    }
+    generation += 1
+    return true
+  }
+
+  const hook = { rewrite }
+  active = hook
+  return {
+    plugin,
+    sweep,
+    generation: () => generation,
+    dispose: () => {
+      if (active === hook) active = undefined
+    },
+  }
+}

package/src/dev.ts

@@ -2,9 +2,9 @@
  * `@nifrajs/web/dev` - the **Bun pipeline's** dev server: one toolchain, no Vite in the process.
  *
  * nifra ships two dev pipelines and the rule between them is that a pipeline owns a whole phase. The
- * Vite server (`@nifrajs/web/vite`) is the default - mature framework plugins, and it resolves SSR as
- * well as the client so both halves agree on every specifier. This is the other one: `Bun.serve` bundles
- * and hot-reloads the client while Bun's runtime resolves SSR. Only one toolchain is present, so the two
+ * Vite server (`@nifrajs/web/vite`) is the Vite-only escape hatch - mature framework plugins, and it
+ * resolves SSR as well as the client so both halves agree on every specifier. This is the other one:
+ * `Bun.serve` bundles and hot-reloads the client while Bun's runtime resolves SSR. Only one toolchain is present, so the two
  * cannot disagree.
  *
  * What you get: React Fast Refresh WITH state preserved - Bun's dev server applies it natively, no plugin
@@ -14,9 +14,9 @@
  * not, and saving it does a clean full reload. Plus no Vite dependency and ONE bundler across dev and
  * production, which is the real prize - the dev/prod seam disappears.
  *
- * What you give up: `*.module.css`. Bun's DEV-server bundler has no CSS-Modules transform (its production
- * `Bun.build` does), so the import compiles to a dangling reference. Plain CSS and Tailwind are fine. The
- * CLI refuses `nifra dev --bun` for a CSS-Modules app rather than serving a broken client.
+ * CSS Modules, server functions, and `*.server` modules use the same production transforms through the
+ * generated Bun config. The CLI owns that config because Bun's HTML dev server accepts plugins only from
+ * `[serve.static] plugins`; direct callers should pass the equivalent plugin through their Bun config.
  *
  * ## How the two halves meet
  *
@@ -38,7 +38,10 @@
  * production, which reads CSS from the build manifest, is perfectly fine.
  *
  * SSR invalidation is Bun's import cache rather than Vite's module graph, so route modules are re-imported
- * under a changing query on each change - which is what `discoverRoutes({ importQuery })` exists for.
+ * under a changing query on each change - which is what `discoverRoutes({ importQuery })` exists for. That
+ * query stops at the route file, so everything BELOW it - components, helpers, `*.server` modules - is
+ * tracked and re-keyed per module by `./dev-ssr-graph.ts`, or SSR would render the code that was on disk
+ * when the server started.
  *
  * Bun-only + build-time; never imported by the edge runtime.
  */
@@ -56,8 +59,10 @@ import { type BuildClientOptions, buildClient } from "./build.ts"
 import { type DevEntryMatch, resolveDevEntry } from "./bun-dev-entry.ts"
 import { createDevDiagnostics } from "./dev-diagnostics.ts"
 import { explainBindFailure } from "./dev-port.ts"
+import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
+import { DEV_HMR_ENV, DEV_ROOT_ENV, DEV_ROUTES_ENV } from "./plugins/kit.ts"
 import { servePublicDir } from "./public-dir.ts"
 
 export { LAST_ERROR_PATH } from "./diagnostic.ts"
@@ -244,13 +249,54 @@ export function injectStyles(html: string, styles: readonly string[]): string {
 export async function createDevServer(options: DevServerOptions): Promise<DevServer> {
   const { createApp, port = DEFAULT_DEV_PORT, routesDir, clientModule } = options
   const serve = bunServe()
+  // Tell the framework compiler plugins they are compiling for a DEV SERVER, so they may emit HMR
+  // wiring. It cannot be a plugin constructor argument: an app builds its `clientPlugins` once in
+  // `nifra.config.ts` and the same objects serve dev and `nifra build`. Guarding the emitted code with
+  // `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so the HMR calls
+  // ship to production. This flag is the phase signal; `nifra build` never sets it.
+  process.env[DEV_HMR_ENV] = "1"
+  // Dev-shaped runtimes for SSR, matching what the client bundle gets: a library ships its dev build
+  // behind the `development` export condition with a `NODE_ENV` fallback for resolvers that set no
+  // conditions, and Bun's runtime (where SSR runs) is one of those. `nifra dev` sets this on the server
+  // process before it reads the app config, which is earlier than this and is the point that matters -
+  // a framework runtime imported through the config has already read the flag by the time this line
+  // runs. This is the floor for a dev server started programmatically. `??=`, so a pinned value stands.
+  process.env.NODE_ENV ??= "development"
+  // `conditions` governs the production client bundle but CANNOT govern the one served here: Bun's
+  // dev-server bundler takes no resolve conditions, from `bunfig.toml` or anywhere else, so a package
+  // with an `exports` map can resolve to a different file in dev than in `nifra build`. SSR is fine -
+  // `nifra dev` passes these to the runtime as `--conditions` when it re-execs - which is exactly why
+  // this is worth a line: the halves of the dev process no longer agree, and the drift is invisible
+  // until production picks the other file. Said once at startup rather than swallowed.
+  if (options.conditions !== undefined && options.conditions.length > 0) {
+    console.warn(
+      `\n[nifra/web/dev] \`conditions: [${options.conditions.map((c) => `"${c}"`).join(", ")}]\` ` +
+        "does not reach the client bundle on the Bun dev pipeline.\n" +
+        "  Bun's dev-server bundler accepts no resolve conditions, so a package with an `exports` map\n" +
+        "  may resolve differently here than in `nifra build`. SSR does honour them.\n" +
+        "  Run `nifra dev --vite` if this app needs exact dev/prod client resolution.\n",
+    )
+  }
   // The app root. `routesDir` is `<app>/routes` by convention, so its parent is the project - the one
   // place a generated entry can sit and still resolve the app's imports.
   const root = resolve(routesDir, "..")
+  // Which files are the app's own components, for the plugins that hot-patch at component granularity
+  // (`devHotComponent`). Announced here rather than passed, for the same reason the flag above is.
+  process.env[DEV_ROOT_ENV] = root
+  process.env[DEV_ROUTES_ENV] = resolve(routesDir)
   // The most recent SSR failure as a structured Diagnostic, scoped to THIS server. Served at
   // LAST_ERROR_PATH so an agent driving the dev server reads the exact failure (code, codeframe, fix) as
   // JSON instead of scraping the overlay. Shared with the Vite adapter so the endpoint can't drift.
   const devDiagnostics = createDevDiagnostics(root)
+  // SSR freshness BELOW the route module. The route-level `importQuery` only ever reloaded the route
+  // itself; everything it imports is tracked here and re-keyed when it changes. Registered now because a
+  // Bun runtime plugin only affects modules loaded after it, and the first route import is `appFor`
+  // below - the CLI's own plugins (CSS Modules, the app's `serverPlugins`) register earlier still, and
+  // being earlier is what gives them first refusal on the specifiers and file types they own. That
+  // ordering is deliberate: a framework plugin compiling `.vue`/`.svelte`/`.tsx` keeps its loader, and
+  // re-keys the imports of what it compiled by handing its output through `rewriteSsrImports`.
+  const ssrGraph = createSsrGraph({ root })
+  ;(await import("bun")).plugin(ssrGraph.plugin)
   const devDir = resolve(root, DEV_DIR)
   const entryPath = resolve(devDir, "entry.tsx")
   const htmlPath = resolve(devDir, "entry.html")
@@ -271,9 +317,9 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   let server: BunServerHandle
   // The last resolved entry, with the time it was resolved. Deliberately short-lived - see `currentEntry`.
   let cache: { readonly entry: DevEntryMatch; readonly at: number } | undefined
-  // The app, tagged with the entry hash it was built against - see `appFor`.
-  let built: { readonly entry: string; readonly app: FetchApp } | undefined
-  let building: { readonly entry: string; readonly promise: Promise<FetchApp> } | undefined
+  // The app, tagged with the build it was made for - see `appFor`.
+  let built: { readonly key: string; readonly app: FetchApp } | undefined
+  let building: { readonly key: string; readonly promise: Promise<FetchApp> } | undefined
   let version = 0
 
   /**
@@ -321,27 +367,38 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
    *
    * The watcher still runs: it regenerates the entry when routes are added or removed, and re-checks for
    * client leaks. It is no longer what keeps SSR correct.
+   *
+   * The entry hash is not the whole marker, though, because it only covers the CLIENT graph. A module
+   * the browser never receives - a `*.server` file, a loader's helper - can change without moving it, so
+   * the key also carries {@link SsrGraph} generation, which counts changes on the SERVER side. Either
+   * one moving rebuilds the app, which is what re-imports the route modules under a fresh query.
    */
-  const appFor = (entrySrc: string): Promise<FetchApp> => {
-    if (built?.entry === entrySrc) return Promise.resolve(built.app)
-    if (building?.entry === entrySrc) return building.promise
+  const appFor = (key: string): Promise<FetchApp> => {
+    if (built?.key === key) return Promise.resolve(built.app)
+    if (building?.key === key) return building.promise
     version += 1
     const promise = Promise.resolve(createApp(CLIENT_ENTRY_PATH, `v=${version}`))
-    building = { entry: entrySrc, promise }
+    building = { key, promise }
     void promise
       .then((next) => {
-        if (building?.entry === entrySrc) {
-          built = { entry: entrySrc, app: next }
+        if (building?.key === key) {
+          built = { key, app: next }
           building = undefined
         }
       })
       .catch(() => {
         // Clear the in-flight marker so the next request retries instead of re-awaiting a failed build.
-        if (building?.entry === entrySrc) building = undefined
+        if (building?.key === key) building = undefined
       })
     return promise
   }
 
+  /** Check the server-side graph for changes, then hand back the app for what is on disk right now. */
+  const appForRequest = (entrySrc: string): Promise<FetchApp> => {
+    ssrGraph.sweep()
+    return appFor(`${entrySrc}#${ssrGraph.generation()}`)
+  }
+
   try {
     server = serve({
       port,
@@ -367,14 +424,17 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
           return new Response(body, { headers })
         }
         // Static probe before routing; a miss returns undefined and falls through, so no route is
-        // shadowed and a page render never pays a filesystem stat (extension-less paths skip it).
+        // shadowed. Every GET/HEAD pays the probe, including page renders and API routes: the handler
+        // serves extension-less files too (an ACME challenge token is the reason), so there is no
+        // cheap prefilter to skip. Dev only - production serves `public/` from the CDN, and a caller
+        // mounting this handler itself can pass `files` to answer a miss without touching the disk.
         const staticFile = await servePublic(req)
         if (staticFile !== undefined) return staticFile
         try {
           // One fresh probe per request: it is both the freshness check for SSR and the stylesheet list,
           // so the page cannot be rendered against a build the browser is not about to load.
           const entry = await currentEntry(true)
-          const res = await (await appFor(entry.src)).fetch(req)
+          const res = await (await appForRequest(entry.src)).fetch(req)
           if (!(res.headers.get("content-type") ?? "").includes("text/html")) return res
           if (entry.styles.length === 0) return res
           const headers = new Headers(res.headers)
@@ -405,7 +465,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
   try {
     // Build once up front so a dev server that cannot find the entry, or whose app fails to construct,
     // fails at startup with a real diagnosis instead of on the first page request.
-    await appFor((await currentEntry()).src)
+    await appForRequest((await currentEntry()).src)
   } catch (err) {
     // Leaving the server up would answer 500s forever, which presents as a running server rather than as
     // the startup failure it is.
@@ -481,6 +541,7 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
       if (timer) clearTimeout(timer)
       clearInterval(topologyTimer)
       for (const file of watched) unwatchFile(file)
+      ssrGraph.dispose()
       server.stop(true)
       rmSync(devDir, { recursive: true, force: true })
     },