@bakery-framework/core 1.2.3 → 2.0.0-alpha.11

package/src/handlers/assets/nm.ts

@@ -1,6 +1,6 @@
 import { bundleModule } from '../../compiler'
 import { Bakery } from '../../core/bakery'
-import { toHash } from '../../utils/common'
+import { Try, toHash } from '../../utils/common'
 import { fs } from '../../utils/fs'
 import { Handler } from '../core/$base'
 
@@ -13,6 +13,52 @@ export class NMHandler extends Handler {
     return path.startsWith('/_nm/')
   }
 
+  /**
+   * The file a `/_nm/` path names.
+   *
+   * **The literal path wins whenever it exists, and the order is the whole
+   * point.** `Bun.build` resolves a directory or package entry itself, with
+   * *browser* conditions — which is what picks `vue`'s `esm-bundler` build over
+   * the CJS one behind its `node` condition. `Bun.resolveSync` has no such
+   * knob: it answers with Bun's own server conditions. Resolving here first and
+   * handing `Bun.build` the concrete file therefore silently downgraded every
+   * package with a `browser`/`node` split — `/_nm/vue` came back as
+   * `index.mjs` re-exporting `vue.cjs.js`, and the browser then rejected
+   * `import { Fragment } from 'vue'`.
+   *
+   * So the literal path goes first whenever it is on disk, and `resolveSync` is
+   * the second candidate rather than the first. It is still needed, for two
+   * distinct cases: a public subpath that does not match the physical layout —
+   * `@vue-material/core` maps `"./utils"` to `./dist/utils/index.js`, so the
+   * documented `@vue-material/core/utils` has no `utils` directory to find and
+   * used to 500 — and a package whose root is declared *only* through
+   * `exports`, where `Bun.build` on the directory answers `ModuleNotFound`
+   * because it looks for `main`/`module` and finds neither.
+   *
+   * Hence a list rather than one answer: the caller bundles the first candidate
+   * that builds. Both orders are wrong on their own.
+   */
+  private static resolveEntry(nmPath: string, nmRoot: string): string[] {
+    const literal = fs.resolve(Bakery.root, nmPath)
+    const candidates = fs.exists(literal) ? [literal] : []
+
+    const specifier = nmPath.replace(/^node_modules\//, '')
+
+    try {
+      const resolved = fs.resolve(Bun.resolveSync(specifier, Bakery.root))
+      // A resolver answer still has to be inside `node_modules`: an `exports`
+      // map and a `browser` field can both point outside the package, and this
+      // path is reachable from a URL.
+      if (resolved.startsWith(`${nmRoot}/`) && resolved !== literal) {
+        candidates.push(resolved)
+      }
+    } catch {
+      // Not exposed by the map, or no map to consult.
+    }
+
+    return candidates.length ? candidates : [literal]
+  }
+
   /**
    * Serve a browser-ready bundle of a file inside `node_modules`.
    *
@@ -21,13 +67,15 @@ export class NMHandler extends Handler {
    * comment names now go through it. This one cannot, and the reason is not
    * the root (it takes a `roots` argument) — it is that `getStatic` answers
    * "is there a plain file literally at this path", and `/_nm/` deliberately
-   * asks a different question. The entry here goes to `Bun.build`, which does
-   * Node resolution: `/_nm/pkg/sub` resolves to `pkg/sub/index.js`, and that is
-   * precisely what the import map's `"<pkg>/": "/_nm/<pkg>/"` prefix entry
-   * (`utils/http/dom.ts`) produces for an extensionless subpath import.
-   * `getStatic` returns `null` for that path — it is a directory — so routing
-   * through it would turn every extensionless subpath import into a 204.
-   * `nm.test.ts` pins both halves of that divergence.
+   * asks a different question: what would an importer of this specifier get?
+   * `resolveEntry` answers it, applying the package's `exports` map, and
+   * `Bun.build` then does directory-index resolution on whatever survives — so
+   * `/_nm/pkg/sub` reaches `pkg/sub/index.js`, which is precisely what the
+   * import map's `"<pkg>/": "/_nm/<pkg>/"` prefix entry (`utils/http/dom.ts`)
+   * produces for an extensionless subpath import. `getStatic` returns `null`
+   * for that path — it is a directory — so routing through it would turn every
+   * extensionless subpath import into a 204. `nm.test.ts` pins both halves of
+   * that divergence.
    *
    * What *was* missing is the second half of the pair. Containment was spelled
    * out here and was correct, but `.forbidden` was never checked, so `/_nm/*`
@@ -43,16 +91,21 @@ export class NMHandler extends Handler {
   static async handle(path: string) {
     const nmPath = path.replace(/^\/_nm\//, 'node_modules/')
     const nmRoot = fs.resolve(Bakery.root, 'node_modules')
-    const nodeModulesPath = fs.resolve(Bakery.root, nmPath)
+    const candidates = this.resolveEntry(nmPath, nmRoot)
 
     // Strictly below the root, so `node_modules` itself is not an entry point.
     // `getStatic` admits `file === root` and then rejects it as a directory;
     // here the same answer has to come from the containment test, because
-    // nothing downstream stats the path.
-    if (!nodeModulesPath.startsWith(`${nmRoot}/`)) return undefined
-    if (fs.isForbidden(nodeModulesPath, nmRoot)) return undefined
+    // nothing downstream stats the path. Every candidate is checked: the
+    // resolver's answer is no more trusted than the URL's.
+    const allowed = candidates.filter(
+      candidate =>
+        candidate.startsWith(`${nmRoot}/`) &&
+        !fs.isForbidden(candidate, nmRoot),
+    )
+    if (!allowed.length) return undefined
 
-    const nmFile = Bun.file(nodeModulesPath)
+    const nmFile = Bun.file(allowed[0])
     const sourceMtime = fs.exists(nmFile) ? nmFile.lastModified : null
 
     const cacheId = toHash(nmPath)
@@ -63,8 +116,14 @@ export class NMHandler extends Handler {
       cacheName,
       sourceMtime,
       async () => {
-        const module = await bundleModule(nodeModulesPath)
-        return module.success && module.content ? module.content : null
+        for (const candidate of allowed) {
+          // Wrapped: an entry point Bun cannot resolve is a *throw*, not a
+          // `success: false`, and that is the expected outcome of the first
+          // candidate for a package whose root exists only in `exports`.
+          const [err, module] = await Try.catch(() => bundleModule(candidate))
+          if (!err && module?.success && module.content) return module.content
+        }
+        return null
       },
     )
 

package/src/handlers/assets/static.ts

@@ -2,7 +2,7 @@ import { Bakery, hostKey } from '../../core/bakery'
 import { matchBlockedCached } from '../../core/context'
 import { toHash } from '../../utils'
 import { fs } from '../../utils/fs'
-import { response } from '../../utils/http'
+import { injectBrand, response } from '../../utils/http'
 import { Handler } from '../core/$base'
 import { ErrorHandler } from '../core/$error'
 import { getStatic } from '../core/$static'
@@ -57,30 +57,73 @@ export class DefaultErrorHandler extends ErrorHandler {
    * error surface — `errorBody` carries the thrown error's stack (that is
    * what the log wants), and handing it to the client verbatim gave any
    * anonymous request source paths and query text in PROD.
+   *
+   * Two pages, split on the same gate `publicBody` uses, failing the same
+   * direction: only an explicit DEV gets the diagnostics page, so an
+   * indeterminate mode discloses nothing. DEV keeps the branded title, the
+   * body in a `<pre>`, and the requester/date footer — and `processResponse`
+   * injects the import map and live reload into it like any page, which is
+   * what makes the overlay work on an error. The production page is the
+   * status line and the public body, nothing else: the footer echoed the
+   * requester's own IP and a server timestamp to anyone who triggered an
+   * error, and the page is branded with `injectBrand` because the injected
+   * import map names every installed package — see the note on the export.
    */
   static handle(_path: string, req: Request, error?: Handler.Error.Data) {
-    const ip = Bakery.server?.requestIP(req)?.address || 'Unknown'
-    const date = new Date().toDateString()
-
     error ||= this.DEFAULT_ERROR
 
+    // No separator without text to separate — an empty-message denial used to
+    // render `<h1>403 - </h1>`. Same rule for the body below: empty renders
+    // as no element, not as a dangling `<pre></pre>`.
+    const heading = Bun.escapeHTML(
+      error.errorText
+        ? `${error.errorCode} - ${error.errorText}`
+        : `${error.errorCode}`,
+    )
+    const body = this.publicBody(error)
+
+    if (import.meta.env.DEV) {
+      const ip = Bakery.server?.requestIP(req)?.address || 'Unknown'
+      const date = new Date().toDateString()
+
+      const errorPage = `
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+            <title>Error ${error.errorCode} | Bakery 🚀</title>
+          </head>
+          <body style="margin: 2rem; font-family: sans-serif;">
+            <h1>${heading}</h1>
+            ${body ? `<pre>${Bun.escapeHTML(body)}</pre>` : ''}
+            <hr />
+            <small>${Bun.escapeHTML(date)} - ${Bun.escapeHTML(ip)}</small>
+          </body>
+        </html>
+      `
+
+      return response.html(errorPage, error.errorCode)
+    }
+
+    // `<p>`, not `<pre>`: outside DEV the body is prose by construction —
+    // `publicBody` replaces a 5xx stack with the generic sentence, and a 4xx
+    // body is authored text.
     const errorPage = `
       <!DOCTYPE html>
       <html lang="en">
         <head>
           <meta charset="UTF-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-          <title>Error ${error.errorCode} | Bakery 🚀</title>
+          <title>Error ${error.errorCode}</title>
         </head>
         <body style="margin: 2rem; font-family: sans-serif;">
-          <h1>${Bun.escapeHTML(`${error.errorCode} - ${error.errorText}`)}</h1>
-          <pre>${Bun.escapeHTML(this.publicBody(error))}</pre>
-          <hr />
-          <small>${Bun.escapeHTML(date)} - ${Bun.escapeHTML(ip)}</small>
+          <h1>${heading}</h1>
+          ${body ? `<p>${Bun.escapeHTML(body)}</p>` : ''}
         </body>
       </html>
     `
 
-    return response.html(errorPage, error.errorCode)
+    return injectBrand(response.html(errorPage, error.errorCode))
   }
 }

package/src/handlers/core/$base.ts

@@ -6,21 +6,43 @@ import { processBody } from '../../utils/http'
 const RX_PARAM = /[[\]{}()*+?.\\^$|]/g
 export const RX_DYNAMIC = /\[([\w$]+)\]/
 export const RX_CATCHALL = /\[\.\.\.([\w$]+)\]/
+export const RX_OPT_CATCHALL = /\[\.\.\.([\w$]+)!\]/
 
 export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
   const cleanPath = path.replace(/\\/g, '/').replace(/^\/+/, '')
   if (!cleanPath) return null
-  if (!RX_DYNAMIC.test(cleanPath) && !RX_CATCHALL.test(cleanPath)) return null
+  // Three disjoint spellings: `!` before the `]` keeps `[...x!]` from
+  // matching either of the other two, so each test sees only its own form.
+  if (
+    !RX_DYNAMIC.test(cleanPath) &&
+    !RX_CATCHALL.test(cleanPath) &&
+    !RX_OPT_CATCHALL.test(cleanPath)
+  ) {
+    return null
+  }
 
   const params: string[] = []
   const segments = cleanPath.split('/')
   const last = segments.length - 1
   let catchAll = false
+  let optionalCatchAll = false
 
   const mappedPaths: string[] = []
   for (let i = 0; i < segments.length; i++) {
     const segment = segments[i]
 
+    const optionalMatch = segment.match(RX_OPT_CATCHALL)
+    if (optionalMatch) {
+      if (i !== last) return null
+      params.push(optionalMatch[1])
+      // The whole segment — separator included — is optional, so the pattern
+      // is assembled below rather than pushed here: `docs/[...slug!]` has to
+      // match `/docs` itself, which `/docs/(.*)` cannot.
+      catchAll = true
+      optionalCatchAll = true
+      continue
+    }
+
     const catchAllMatch = segment.match(RX_CATCHALL)
     if (catchAllMatch) {
       // Only terminal: a segment after `[...x]` has no unambiguous meaning
@@ -30,7 +52,9 @@ export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
       params.push(catchAllMatch[1])
       // `.+` rather than `.*`: the catch-all requires at least one segment,
       // so `docs/[...slug]` does not shadow a `docs/index` sibling for
-      // `/docs` itself.
+      // `/docs` itself. `[...slug!]` is the spelling that opts into the
+      // bare directory — and an index sibling still wins there, because
+      // static discovery runs before dynamic in `resolveRouteFile`.
       mappedPaths.push('(.+)')
       catchAll = true
       continue
@@ -46,10 +70,16 @@ export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
     mappedPaths.push(segment.replace(RX_PARAM, '\\$&'))
   }
 
+  const joined = mappedPaths.join('/')
+  const body = optionalCatchAll
+    ? `${joined ? `/${joined}` : ''}(?:/(.*))?`
+    : `/${joined}`
+
   return {
-    pattern: new RegExp(`^/${mappedPaths.join('/')}(?:\\.([a-z]*))?$`),
+    pattern: new RegExp(`^${body}(?:\\.([a-z]*))?$`),
     params,
     catchAll,
+    optionalCatchAll,
   }
 }
 
@@ -62,8 +92,9 @@ export namespace RouteData {
     readonly valid: boolean
     readonly isDynamic: boolean
     readonly catchAll: boolean
+    readonly optionalCatchAll: boolean
     readonly regex: RegExp | null
-    getParams(path: string): MapOf<string> | null
+    getParams(path: string): MapOf<string | string[]> | null
   }
 
   export type Meta = {
@@ -92,6 +123,7 @@ export class RouteData {
     readonly path: fs.RelativePath
     readonly regex: RegExp | null
     readonly catchAll: boolean
+    readonly optionalCatchAll: boolean
 
     constructor(filePath: fs.AbsolutePath, path: fs.RelativePath) {
       this.filePath = fs.resolve(filePath) as fs.AbsolutePath
@@ -101,6 +133,7 @@ export class RouteData {
       this.regex = route?.pattern || null
       this.params = route?.params || []
       this.catchAll = route?.catchAll || false
+      this.optionalCatchAll = route?.optionalCatchAll || false
     }
 
     get file() {
@@ -115,17 +148,28 @@ export class RouteData {
       return this.regex !== null
     }
 
-    getParams(path: string): MapOf<string> | null {
+    getParams(path: string): MapOf<string | string[]> | null {
       if (!this.regex) return null
       const cleanPath = path.startsWith('/') ? path : `/${path}`
       const match = cleanPath.match(this.regex)
       if (!match) return null
 
-      const boundParams: MapOf<string> = {}
+      const boundParams: MapOf<string | string[]> = {}
       for (let i = 0; i < this.params.length; i++) {
-        boundParams[this.params[i]] = match[i + 1]
+        const value = match[i + 1]
+        // The catch-all is always terminal, so it is always the last param —
+        // and it binds as the *segments*, not the joined string: every
+        // consumer was calling `.split('/')` on it anyway, and the joined
+        // form silently conflated `/docs/a%2Fb` with `/docs/a/b`. A bare
+        // directory under `[...name!]` binds `[]`, which is also what makes
+        // "no rest" distinguishable from a single empty segment.
+        if (this.catchAll && i === this.params.length - 1) {
+          boundParams[this.params[i]] = value ? value.split('/') : []
+          continue
+        }
+        boundParams[this.params[i]] = value
       }
-      return boundParams as MapOf<string>
+      return boundParams
     }
   }
 }
@@ -147,6 +191,8 @@ export namespace Handler {
       params: string[]
       /** True when the final segment is a `[...name]` multi-segment matcher. */
       catchAll?: boolean
+      /** True for the `[[...name]]` form, which also matches its bare directory. */
+      optionalCatchAll?: boolean
     }
   }
 
@@ -207,6 +253,23 @@ export class Handler {
    */
   static servesFiles = true
 
+  /**
+   * The URL prefix this handler owns as a complete user-facing surface —
+   * `'/_dashboard'`, `'/_db'` — or `null` for the ordinary case of a handler
+   * that answers by extension or content rather than by prefix.
+   *
+   * This exists so one surface can ask whether another is mounted without
+   * probing it. The dashboard used to detect the explorer by calling every
+   * registered handler's `canHandle('/_db')` with a control path to exclude
+   * the priority-0 catch-all — it worked, and the `as any` it needed was the
+   * tell that the registry could not say what a handler serves. A declaration
+   * is that answer. It is deliberately *not* consulted by routing: `canHandle`
+   * stays the authority on requests, so a stale or missing namespace can
+   * misdescribe a handler to the dashboard nav but can never misroute a
+   * request.
+   */
+  static namespace: string | null = null
+
   protected constructor() {}
 
   static get cache(): HandlerCache<string, Route.Info> {

package/src/handlers/core/$dynamic.ts

@@ -10,9 +10,10 @@ import {
   type Route,
   RX_CATCHALL,
   RX_DYNAMIC,
+  RX_OPT_CATCHALL,
 } from './$base'
 import { resolveMount } from './$mounts'
-import { getRoute } from './$routing'
+import { getRoute, servedSourceExists } from './$routing'
 
 const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
 
@@ -73,9 +74,17 @@ export class DynamicHandler extends Handler {
 
   static canHandle(path: string, req?: Request): MixedPromise<boolean>
   static async canHandle(path: string) {
-    // A request path spelled like a route template ('/blog/[id]' or
-    // '/docs/[...slug]') addresses the template file, not a route.
-    if (RX_DYNAMIC.test(path) || RX_CATCHALL.test(path)) return false
+    // A request path spelled like a route template ('/blog/[id]',
+    // '/docs/[...slug]' or '/docs/[...slug!]') addresses the template file,
+    // not a route. `RX_OPT_CATCHALL` is tested too because the `!` keeps the
+    // optional spelling from matching `RX_CATCHALL`.
+    if (
+      RX_DYNAMIC.test(path) ||
+      RX_CATCHALL.test(path) ||
+      RX_OPT_CATCHALL.test(path)
+    ) {
+      return false
+    }
     if (this.cache.has(hostKey(path))) return true
     // The dynamic half of the line above. A dynamic route is never written to
     // `this.cache`, so without this every request to one ran `resolveRoute`
@@ -149,18 +158,20 @@ export class DynamicHandler extends Handler {
     }
     if (deferred) {
       // A real file always beats a catch-all, whatever handler would serve
-      // it: when the requested path names an existing file, every catch-all
-      // declines so the file's own handler (possibly lower-priority — CSS
-      // falls all the way to StaticHandler) gets asked. One stat, paid only
-      // when a catch-all is about to answer. `getCatchAllRoute` applies the
-      // same rule on the discovery path; the two must agree — including the
+      // it: when the requested path names an existing file — literally, or
+      // through a compiled extension like `provides.ts` at `/provides.js`
+      // (see `servedSourceExists`) — every catch-all declines so the file's
+      // own handler (possibly lower-priority — CSS falls all the way to
+      // StaticHandler) gets asked. A handful of stats, paid only when a
+      // catch-all is about to answer. `getCatchAllRoute` applies the same
+      // rule on the discovery path; the two must agree — including the
       // containment clamp: `root + path` is unresolved, so a `..` in the
       // path would have `statSync` resolve it outside the root and turn this
       // into an existence probe. See the comment there.
       const target = fs.resolve(root, `.${path}`)
       if (
         (target === root || target.startsWith(`${root}/`)) &&
-        fs.isFileSync(target)
+        servedSourceExists(target)
       ) {
         return null
       }

package/src/handlers/core/$error.ts

@@ -193,7 +193,16 @@ export class ErrorHandler extends Handler {
         ...this.DEFAULT_ERROR,
         errorCode: error.status,
         errorText: error.statusText,
-        errorBody: `${error.status}: "${error.statusText}"`,
+        // The reason-phrase is optional — `new Response(null, { status })`
+        // leaves it `''`, and the framework's own forbidden-path denial is
+        // exactly that shape — so the quoting is conditional: a synthesized
+        // `403: ""` rendered a literal quoted empty string on the error page.
+        // The bare status, not `''`, because this string is also the default
+        // `onError` log line (`403 at /path`); an empty body would log
+        // ` at /path`.
+        errorBody: error.statusText
+          ? `${error.status}: "${error.statusText}"`
+          : String(error.status),
       }
     }
 

package/src/handlers/core/$registry.ts

@@ -30,11 +30,16 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     }
   }
 
-  set(handlerClass: any, priority: number = 10): this {
-    super.set(handlerClass, priority)
+  /** Drop the derived views. Every mutation has to call this, not just `set`. */
+  private invalidate(): void {
     this.cachedList = null
     this.cachedGates = null
     this.cachedOrder = null
+  }
+
+  set(handlerClass: any, priority: number = 10): this {
+    super.set(handlerClass, priority)
+    this.invalidate()
     return this
   }
 
@@ -42,6 +47,30 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     return this.set(handlerClass, priority)
   }
 
+  /**
+   * `delete` and `clear` invalidate too, and neither used to.
+   *
+   * `list()` memoizes the sorted handler array and only `set` cleared it, so a
+   * removed handler stayed in the list — and therefore stayed *in the request
+   * pipeline* — until something happened to add one. Registration is
+   * add-only in a served process, which is why this never bit: it is reachable
+   * only by code that unregisters, and the first thing to do that was a test.
+   *
+   * A cache that survives the removal of its input is wrong regardless of who
+   * currently calls it, and "nothing removes handlers today" is a property of
+   * the callers rather than of this class.
+   */
+  override delete(handlerClass: any): boolean {
+    const removed = super.delete(handlerClass)
+    if (removed) this.invalidate()
+    return removed
+  }
+
+  override clear(): void {
+    super.clear()
+    this.invalidate()
+  }
+
   list(): T[] {
     if (this.cachedList) {
       return this.cachedList

package/src/handlers/core/$routing.ts

@@ -21,15 +21,37 @@ export type RouteScanOptions = {
 const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 
 // The single-param route forms, in the order they are tried: `[name].ext`
-// first, then the escaped-literal `*.ext`. Built here rather than twice inside
+// first, then the literal-asterisk `*.ext`. Built here rather than twice inside
 // `routeGlobs` — the `dynamicOnly` branch and the combined branch returned
 // character-identical pairs, and the two must stay in step or a route form
 // resolves under one caller and not the other. A function, not a hoisted
 // constant: `ext` varies per handler, and `staticOnly` returns before it needs
 // them at all.
-const dynamicGlobs = (ext: string) => [
+//
+// **The literal asterisk is a character class, `[*]`, never the escape `\*`.**
+// A backslash is the obvious spelling and is unusable on Windows, where `\` is
+// a path separator: Bun read `\*.*` as a drive-absolute pattern, ignored the
+// `cwd` in `GETFILE` entirely, and matched files at `C:\`. A route lookup under
+// a serve root six levels down returned `C:\$WINRE_BACKUP_PARTITION.MARKER`,
+// and `fs.isForbidden` — whose walk is bounded by `startsWith(root)` — waved it
+// through because an out-of-root path skipped the loop and answered "allowed".
+// That clamp now fails closed, so this is belt and braces; both halves are
+// pinned, and neither test can see the other's bug.
+//
+// Measured with a scan whose cwd was a temp directory holding one file: `[*]`
+// yields nothing, `\*` yields four files from the drive root. The escape is
+// also unreachable on Windows in the direction it was meant for — `*` is a
+// reserved character in a Windows filename, so a route file literally named
+// `*.ts` can only exist on POSIX, where both spellings match it identically
+// (verified on Linux). The character class costs nothing and means the same
+// thing on both platforms.
+//
+// Exported only as a test seam: with the clamp in place no test driving
+// `getRoute` can tell the two spellings apart — verified by reverting this line
+// and watching all 17 pass — so the pattern has to be asserted directly.
+export const dynamicGlobs = (ext: string) => [
   new Bun.Glob(`[[][!.]*${ext || '.*'}`),
-  new Bun.Glob(`\\*${ext || '.*'}`),
+  new Bun.Glob(`[*]${ext || '.*'}`),
 ]
 
 const routeGlobs = (
@@ -72,6 +94,43 @@ const routeGlobs = (
  * is not a file and does not trigger the yield. `findDynamicRoute` applies
  * the same rule on the cached path; the two must agree.
  */
+/**
+ * Does the requested path name a file some handler serves at that URL?
+ *
+ * The "a real file always beats a catch-all" rule used to stat the literal
+ * path only, which misses every *compiled* URL: `TSHandler` serves
+ * `provides.ts` at `/teacher/provides` and `/teacher/provides.js`, so neither
+ * spelling named a file on disk and a Vue catch-all above it (priority 58 vs
+ * 50) served HTML to a browser that asked for a module. The probe now also
+ * tries the registered dynamic extensions against the extensionless base —
+ * the same mapping the serving handlers apply, read from the live registry so
+ * a plugin's extension (`.vue`) counts without core naming it.
+ *
+ * The caller clamps `target` inside the root before asking; appending an
+ * extension cannot escape it.
+ */
+export function servedSourceExists(target: string): boolean {
+  if (fs.isFileSync(target)) return true
+
+  const base = target.endsWith('.js') ? target.slice(0, -3) : target
+  for (const handler of Bakery.handlers.fetch.keys()) {
+    let exts: unknown
+    try {
+      exts = (handler as { config?: { ext?: unknown } }).config?.ext
+    } catch {
+      // A config getter that needs state this process lacks — a handler with
+      // no ext table cannot claim a source file either way.
+      continue
+    }
+    if (!Array.isArray(exts)) continue
+    for (const ext of exts) {
+      if (fs.isFileSync(`${base}.${ext}`)) return true
+    }
+  }
+
+  return false
+}
+
 async function getCatchAllRoute(
   ext: string,
   dir: fs.AbsolutePath,
@@ -98,7 +157,7 @@ async function getCatchAllRoute(
     // whose name merely begins with it.
     if (
       (target === dir || target.startsWith(`${dir}/`)) &&
-      fs.isFileSync(target)
+      servedSourceExists(target)
     ) {
       return null
     }
@@ -106,7 +165,14 @@ async function getCatchAllRoute(
 
   const file = fs.resolve(found.value)
   if (fs.isForbidden(file, root)) return null
-  return new RouteData.Info(file, fs.relative(root, file))
+  const info = new RouteData.Info(file, fs.relative(root, file))
+
+  // A bare-directory request (`/docs` with no index) reaches here with no
+  // rest segments, and only the `[...name!]` spelling opted into claiming
+  // it — the plain form keeps requiring at least one segment.
+  if (!restSegments.length && !info.optionalCatchAll) return null
+
+  return info
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: request-to-route dispatcher
@@ -177,12 +243,17 @@ export async function getRoute(
       if (route) return route
     }
 
-    // `first === 'index'` covers the bare-directory request (`/docs` arrives
-    // here as an injected 'index' segment): the catch-all pattern requires at
-    // least one rest segment, so it cannot match that request — returning the
-    // Info anyway would claim the route with null params.
-    if (!options.staticOnly && first !== 'index') {
-      return await getCatchAllRoute(ext, dir, root, [first])
+    // `first === 'index'` is the bare-directory request (`/docs` arrives here
+    // as an injected 'index' segment, after no index file matched). The plain
+    // `[...name]` pattern requires at least one rest segment and cannot claim
+    // it; `[...name!]` exists to — `getCatchAllRoute` tells them apart.
+    if (!options.staticOnly) {
+      return await getCatchAllRoute(
+        ext,
+        dir,
+        root,
+        first === 'index' ? [] : [first],
+      )
     }
   }