@bakery-framework/core 1.2.2 → 2.0.0-alpha.1

package/src/compiler/tsconfig-sync.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs'
 import { Bakery } from '../core/bakery'
 import { errorMsg, serveLog } from '../logger'
 import type { PluginTsProject } from '../plugins/types'
@@ -69,6 +70,7 @@ export function coreProjects(): PluginTsProject[] {
   return [
     {
       name: 'server',
+      server: true,
       extends: '@bakery-framework/core/tsconfig.server.json',
       // Repeated rather than inherited: Bun's runtime does not follow
       // `extends` into a package specifier, only a relative path.
@@ -138,6 +140,77 @@ function resolveFilesEntry(entry: string): string | null {
   }
 }
 
+/**
+ * The `files` the extended base config declares, resolved for the generated one.
+ *
+ * **TypeScript's rule is that a child's `files` *replaces* the parent's, and
+ * that rule silently disarmed every project a plugin contributes.**
+ * `tsconfig.vue.json` lists core's three ambient declarations — `global.d.ts`,
+ * `shared.d.ts`, `types.d.ts` — which is where `Bakery`, `AppConfig`, the JSX
+ * namespace and `Request.session` come from. `@bakery-framework/plugin-vue`
+ * declares one `files` entry of its own for `vue.d.ts`, and that one entry
+ * replaced all three: measured on a real app, the generated `vue` project loaded
+ * **zero** of them.
+ *
+ * It hid because `vue.d.ts` happens to declare `req` and `body` itself, so the
+ * globals an SFC reaches for most still resolved. Everything else — `Bakery`,
+ * `MapOf`, the JSX namespace — was quietly missing.
+ *
+ * So the base's list is read and merged rather than inherited. Paths inside it
+ * are relative to *that* file, which is the property the whole arrangement rests
+ * on and the reason they cannot simply be copied across.
+ */
+function readBase(extendsSpecifier: string): string[] {
+  try {
+    const base = Bun.resolveSync(extendsSpecifier, APP_DIR)
+    const parsed = parseJSONC(readFileSync(base, 'utf8'))
+    const list: string[] = Array.isArray(parsed?.files) ? parsed.files : []
+    const baseDir = fs.dirname(base)
+
+    return list.map(entry => {
+      const abs = fs.resolve(baseDir, entry)
+      const rel = fs.relative(PROJECT_DIR, abs).replace(/\\/g, '/')
+      return RE_RELATIVE.test(rel) ? rel : `./${rel}`
+    })
+  } catch {
+    // A base that cannot be read is not fatal: the project still compiles, it
+    // just loses the ambients — which is the status quo this repairs, not a
+    // regression. Assume client-side, which is the conservative half.
+    return []
+  }
+}
+
+/**
+ * The app file carrying `declare module '@bakery-framework/orm/schema-registry'`.
+ *
+ * Declaration merging only happens if the declaring file is in the program, and
+ * it reached exactly one project: `server`, because that is the only one whose
+ * `include` covers `orm/**`. Everywhere else `SchemaRegistry` stayed empty,
+ * `Registered` resolved to `never`, and every table fell back to
+ * `MapOf<MapOf<any>>` — the ORM's documented untyped mode, arrived at by
+ * accident. It does not error; it just stops checking.
+ *
+ * **Server-side projects only.** The client project deliberately does not get
+ * it: the ORM is server-only, so a browser file importing `DB` should fail to
+ * typecheck rather than be helpfully typed. That is not only a preference —
+ * `@bakery-framework/orm` ships TypeScript source that calls `Bun.*`, so pulling
+ * it into a config without `bun-types` produces errors from inside the package
+ * rather than types for the app. Measured when this was applied to every
+ * project: 187 new errors in `client`.
+ */
+function schemaRegistrationFile(): string | null {
+  const configured = Bakery.config.schema
+  const candidates = configured
+    ? [configured, `${configured}/index.ts`]
+    : ['orm/index.ts', 'schema.ts']
+
+  for (const rel of candidates) {
+    const abs = fs.resolve(APP_DIR, rel)
+    if (fs.isFileSync(abs)) return abs
+  }
+  return null
+}
+
 /** Every project: core's two, plus whatever the loaded plugins contribute. */
 function allProjects(): PluginTsProject[] {
   const projects = coreProjects()
@@ -174,9 +247,16 @@ function allProjects(): PluginTsProject[] {
  */
 export async function writeProjects(paths: MapOf<string[]>): Promise<string[]> {
   const written: string[] = []
+  const found = schemaRegistrationFile()
+  const registrationFile = found
+    ? (() => {
+        const rel = fs.relative(PROJECT_DIR, found).replace(/\\/g, '/')
+        return RE_RELATIVE.test(rel) ? rel : `./${rel}`
+      })()
+    : null
 
   for (const project of allProjects()) {
-    const files = (project.files ?? [])
+    const own = (project.files ?? [])
       .map(entry => {
         const resolved = resolveFilesEntry(entry)
         if (!resolved) {
@@ -186,6 +266,24 @@ export async function writeProjects(paths: MapOf<string[]>): Promise<string[]> {
       })
       .filter((f): f is string => f !== null)
 
+    const baseFiles = readBase(project.extends)
+
+    // The schema registration goes to every server-side project, so an SFC's
+    // `<script>` gets the app's real tables rather than the `any` fallback. The
+    // server project already reaches it through `include: ['orm/**']`; adding it
+    // to `files` there is a harmless duplicate and keeps the rule in one place.
+    const registration =
+      project.server && registrationFile ? [registrationFile] : []
+
+    // The base's own `files` are merged back in whenever this project declares
+    // any of its own, because a child's `files` *replaces* the parent's — see
+    // `readBase`. Left entirely empty, TypeScript inherits correctly and there
+    // is nothing to repair.
+    const declared = [...own, ...registration]
+    const files = declared.length
+      ? [...new Set([...baseFiles, ...declared])]
+      : []
+
     const config: Record<string, unknown> = {
       $comment:
         'GENERATED by Bakery on dev boot. Edits are lost; change the plugin or server.config.ts instead.',

package/src/core/bakery.ts

@@ -2,7 +2,7 @@ import { HandlerMap } from '../handlers/core/$registry'
 import { fs } from '../utils/fs'
 import { SharedMemoryPool } from '../utils/shared-pool'
 import { getConfig, resolveHostname } from './config'
-import { getAppVersion, hostStore } from './context'
+import { cacheDir, dataDir, getAppVersion, hostStore } from './context'
 
 export type { HostContext } from './context'
 export { hostStore } from './context'
@@ -70,17 +70,16 @@ export const Bakery: globalThis.Bakery = {
     return getAppVersion()
   },
   sharedPool: new SharedMemoryPool(1024 * 1024),
-  // The disposable directory is the hidden one, and the precious one is not.
-  // This is the reverse of the old `.bakery/cache` + `.data` pairing, and the
-  // reversal is the whole point: `.cache` is wiped by the framework itself on
-  // every version bump and dev<->prod switch, so a `rm -rf .*` or a "clean out
-  // the dotfiles" sweep does exactly what the framework already does. The
-  // database is not disposable, so it does not live behind a leading dot where
-  // such a sweep can reach it.
-  cacheDir: `${fs.cwd}/.cache`,
-  // Holds the database and its backups. Visible, and deliberately not under
-  // `.cache`: clearing a cache must never be able to destroy data.
-  dataDir: `${fs.cwd}/bakery`,
+  // Defined in `core/context.ts`, which is low enough that a module needing a
+  // path does not have to import `Bakery` to get one — reaching them through
+  // here is what closed the logger cycle. These stay the reading surface for
+  // application and framework code; context is the single definition.
+  //
+  // Called here rather than forwarded through a getter, so these remain plain
+  // writable properties: `nm.test.ts` repoints them at a fixture tree, which a
+  // getter turns into `TypeError: Attempted to assign to readonly property`.
+  cacheDir: cacheDir(),
+  dataDir: dataDir(),
   startNs: Bun.nanoseconds(),
   handlers: {
     fetch: new HandlerMap(),

package/src/core/cache-version.ts

@@ -100,12 +100,37 @@ async function run(): Promise<void> {
  */
 export const __wipeCacheDir = wipe
 
+/**
+ * The one thing in `.cache/` the wipe must not take.
+ *
+ * **The app's committed `tsconfig.json` *references* `.cache/tsconfig/*.json`,
+ * so deleting them breaks the editor for the whole project** — not one setting,
+ * everything. TypeScript reports `TS6053: File '…/server.json' not found` for
+ * each reference, has no project left to put a file in, and falls back to an
+ * inferred one with no ambients: `req.session`, `Bakery`, the JSX namespace and
+ * the app's own schema types all stop resolving at once.
+ *
+ * That happens on every framework upgrade, because the version wipe is keyed on
+ * the framework version among others. The developer sees their editor lose every
+ * type the moment they bump a patch, and nothing says why — the files come back
+ * only on the next `bun run dev`, which is not an obvious remedy for "my types
+ * vanished".
+ *
+ * Keeping them is safe in the direction that matters. A stale project is
+ * regenerated on the next dev boot and is, in the meantime, *approximately
+ * right* — while a missing one is catastrophically wrong. Nothing is executed
+ * from these files either: they configure a typechecker, so the "never read a
+ * cache an older framework wrote" rule the wipe exists to enforce does not apply.
+ */
+const WIPE_KEEP = new Set(['tsconfig'])
+
 async function wipe(dir: string): Promise<string[]> {
   if (!fs.exists(dir)) return []
   const [readErr, entries] = await Try.catch(() => readdir(dir))
   if (readErr || !entries) return ['<unreadable>']
 
   for (const entry of entries) {
+    if (WIPE_KEEP.has(entry)) continue
     // Errors are deliberately not swallowed *silently* here — each failure is
     // collected and reported by the caller.
     await Try.catch(() =>
@@ -115,5 +140,7 @@ async function wipe(dir: string): Promise<string[]> {
 
   const [rereadErr, left] = await Try.catch(() => readdir(dir))
   if (rereadErr) return ['<unreadable>']
-  return left ?? []
+  // Kept entries are not survivors of a failed delete, and reporting them as
+  // such would make the caller withhold the "cache is current" marker forever.
+  return (left ?? []).filter(entry => !WIPE_KEEP.has(entry))
 }

package/src/core/context.ts

@@ -29,6 +29,40 @@ export type HostContext = {
 
 export const hostStore = new AsyncLocalStorage<HostContext>()
 
+/**
+ * The two runtime directories, defined here rather than on `Bakery`.
+ *
+ * `Bakery.cacheDir` / `Bakery.dataDir` remain the way application and framework
+ * code reads them — these are the single definition those two forward to, and
+ * still the only writer of either path. They live in this module because it is
+ * low enough to be imported without pulling in `core/config`, and therefore
+ * without pulling in the logger: `compiler/prompt-tracker.ts` needs the cache
+ * directory and reaching it through `Bakery` closed a module cycle that made
+ * the whole package unimportable. See the note on `prompt-tracker.ts`.
+ *
+ * **Functions, not constants, and that is not a style choice.** `utils/fs.ts`
+ * imports this module for `hostStore`, so the two are themselves a cycle: a
+ * top-level `` `${fs.cwd}/.cache` `` here is evaluated with `fs` still
+ * uninitialised whenever `core/context` is reached first, and throws
+ * `TypeError: undefined is not an object`. Reading `fs.cwd` at call time is
+ * what makes the order irrelevant.
+ *
+ * The disposable directory is the hidden one, and the precious one is not. This
+ * is the reverse of the old `.bakery/cache` + `.data` pairing, and the reversal
+ * is the whole point: `.cache` is wiped by the framework itself on every version
+ * bump and dev<->prod switch, so a `rm -rf .*` or a "clean out the dotfiles"
+ * sweep does exactly what the framework already does. The database is not
+ * disposable, so it does not live behind a leading dot where such a sweep can
+ * reach it, and never under `.cache` — clearing a cache must not destroy data.
+ */
+export function cacheDir(): string {
+  return `${fs.cwd}/.cache`
+}
+
+export function dataDir(): string {
+  return `${fs.cwd}/bakery`
+}
+
 /**
  * `matchBlocked`, deduplicated within the current request.
  *
@@ -51,14 +85,6 @@ export function matchBlockedCached(
   return verdict
 }
 
-/**
- * The **application's** version, from `<cwd>/package.json`.
- *
- * Named `getBakeryVersion` until 2026-08-09, which is exactly the wrong name:
- * it reads the package.json of whatever is being served, not the framework's.
- * That misnomer hid a real bug for as long as it existed — see
- * {@link getFrameworkVersion}.
- */
 /**
  * What each version reader returns when it cannot read its manifest.
  *
@@ -78,6 +104,14 @@ const UNKNOWN_APP = '0.0.0-unknown-app'
 const UNKNOWN_FW = '0.0.0-unknown-framework'
 
 let _appVersion: string | null = null
+
+/**
+ * The **application's** version, from `<cwd>/package.json`.
+ *
+ * Not the framework's — this reads the manifest of whatever is being served.
+ * The distinction is load-bearing for cache invalidation; see
+ * {@link getFrameworkVersion}.
+ */
 export function getAppVersion() {
   if (_appVersion) return _appVersion
   try {

package/src/core/index.ts

@@ -19,6 +19,7 @@ export type {
   MixedPromise,
   RouteBody,
   RouteHandler,
+  RouteParam,
   RouteResponse,
   Wrapped,
 } from '../types'

package/src/core/init.ts

@@ -1,3 +1,4 @@
+import { randomId } from '../utils/isomorphic/misc'
 import { createElement, Fragment, html } from './jsx'
 
 const hasDevWorkerArg = process.argv.includes('--dev-worker')
@@ -84,6 +85,11 @@ Object.assign(globalThis, {
   createElement,
   Fragment,
   html,
+  // The same value the browser runtime binds (`client/utils.ts`), so code
+  // that moves between an SFC's browser script and its server block — where
+  // it runs as a bare global either way — does not lose the name. Declared
+  // once, in `shared.d.ts`.
+  randomId,
 })
 
 process.on('SIGHUP', () => {})

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/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
     }
   }
 

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
       }