@vercel/python 14.1.0 → 14.2.0

package/dist/index.js

@@ -3328,9 +3328,9 @@ var require_pep440 = __commonJS({
 var require_lib = __commonJS({
   "../../node_modules/.pnpm/which@3.0.0/node_modules/which/lib/index.js"(exports, module2) {
     var isexe = require_isexe();
-    var { join: join21, delimiter: delimiter2, sep: sep6, posix } = require("path");
+    var { join: join21, delimiter: delimiter2, sep: sep6, posix: posix4 } = require("path");
     var isWindows = process.platform === "win32";
-    var rSlash = new RegExp(`[${posix.sep}${sep6 === posix.sep ? "" : sep6}]`.replace(/(\\)/g, "\\$1"));
+    var rSlash = new RegExp(`[${posix4.sep}${sep6 === posix4.sep ? "" : sep6}]`.replace(/(\\)/g, "\\$1"));
     var rRel = new RegExp(`^\\.${rSlash.source}`);
     var getNotFoundError = (cmd) => Object.assign(new Error(`not found: ${cmd}`), { code: "ENOENT" });
     var getPathInfo = (cmd, {
@@ -10864,6 +10864,9 @@ function installGlobalCleanupHandlers() {
     killAll();
   });
 }
+function escapePythonStringContents(value) {
+  return JSON.stringify(value).slice(1, -1);
+}
 function createDevShim(workPath, entry, modulePath, serviceName, framework, variableName) {
   try {
     const vercelPythonDir = serviceName ? (0, import_path13.join)(workPath, ".vercel", "python", "services", serviceName) : (0, import_path13.join)(workPath, ".vercel", "python");
@@ -10875,7 +10878,7 @@ function createDevShim(workPath, entry, modulePath, serviceName, framework, vari
       qualifiedModule = `${pkgName}.${modulePath}`;
       extraPythonPath = (0, import_path13.dirname)(workPath);
     }
-    const entryAbs = (0, import_path13.join)(workPath, entry);
+    const entryAbs = import_path13.posix.join(workPath.replace(/\\/g, "/"), entry);
     const shimPath = (0, import_path13.join)(vercelPythonDir, `${DEV_SHIM_MODULE}.py`);
     const templatePath = (0, import_path13.join)(
       __dirname,
@@ -10884,7 +10887,13 @@ function createDevShim(workPath, entry, modulePath, serviceName, framework, vari
       `${DEV_SHIM_MODULE}.py`
     );
     const template = (0, import_fs13.readFileSync)(templatePath, "utf8");
-    const shimSource = template.replace(/__VC_DEV_MODULE_NAME__/g, qualifiedModule).replace(/__VC_DEV_ENTRY_ABS__/g, entryAbs).replace(/__VC_DEV_FRAMEWORK__/g, framework).replace(/__VC_DEV_VARIABLE_NAME__/g, variableName);
+    const shimSource = template.replace(
+      /__VC_DEV_MODULE_NAME__/g,
+      escapePythonStringContents(qualifiedModule)
+    ).replace(/__VC_DEV_ENTRY_ABS__/g, escapePythonStringContents(entryAbs)).replace(/__VC_DEV_FRAMEWORK__/g, escapePythonStringContents(framework)).replace(
+      /__VC_DEV_VARIABLE_NAME__/g,
+      escapePythonStringContents(variableName)
+    );
     (0, import_fs13.writeFileSync)(shimPath, shimSource, "utf8");
     (0, import_build_utils15.debug)(`Prepared Python dev shim at ${shimPath}`);
     return {
@@ -11418,7 +11427,7 @@ var litellmQuirk = {
       if (configName) {
         (0, import_build_utils16.debug)(`LiteLLM quirk: found config at ${configName}`);
         buildEnv.CONFIG_FILE_PATH = (0, import_path14.join)(ctx.workPath, configName);
-        env.CONFIG_FILE_PATH = (0, import_path14.join)(LAMBDA_ROOT, configName);
+        env.CONFIG_FILE_PATH = import_path14.posix.join(LAMBDA_ROOT, configName);
       }
     } else {
       (0, import_build_utils16.debug)(
@@ -11546,7 +11555,7 @@ var prismaQuirk = {
   async run(ctx) {
     const { venvPath, pythonEnv, workPath } = ctx;
     const pythonPath = getVenvPythonBin(venvPath);
-    const runtimeCacheDir = (0, import_path15.join)(
+    const runtimeCacheDir = import_path15.posix.join(
       LAMBDA_ROOT2,
       resolveVendorDir(),
       "prisma",
@@ -11961,7 +11970,7 @@ ${stderr}`);
     (0, import_build_utils20.debug)(
       `FastAPI: static discovery failed: ${err?.stderr ?? err?.message ?? err}`
     );
-    return { mounts: [], shadowRoutes: [] };
+    return { mounts: [], shadowRoutes: [], excludedFiles: [] };
   } finally {
     await import_fs17.default.promises.rm(outputPath, { force: true });
   }
@@ -11969,6 +11978,9 @@ ${stderr}`);
 function trimTrailingSlashes(urlPath) {
   return urlPath.replace(/\/+$/, "");
 }
+function trimSlashes(urlPath) {
+  return urlPath.replace(/^\/+|\/+$/g, "");
+}
 function mountCovers(base, urlPath) {
   return base === "" || urlPath === base || urlPath.startsWith(base + "/");
 }
@@ -11976,15 +11988,18 @@ function cdnUrlPath(outputStaticDir, destPath) {
   const rel = (0, import_path17.relative)(outputStaticDir, destPath);
   return rel === "" ? "/" : "/" + rel.split(import_path17.sep).join("/");
 }
-async function copyFastAPIStaticMounts(mounts, outputStaticDir) {
-  const ordered = [
+function byCopyPriority(mounts) {
+  return [
     ...mounts.filter((m) => !m.frontend),
     ...mounts.filter((m) => m.frontend).sort((a, b) => b.urlPath.length - a.urlPath.length)
   ];
+}
+async function copyFastAPIStaticMounts(mounts, outputStaticDir, excludedFiles = []) {
+  const excluded = new Set(excludedFiles);
   const higherPriority = [];
   const copied = [];
-  for (const mount of ordered) {
-    const dest = (0, import_path17.join)(outputStaticDir, mount.urlPath.replace(/^\/+|\/+$/g, ""));
+  for (const mount of byCopyPriority(mounts)) {
+    const dest = (0, import_path17.join)(outputStaticDir, trimSlashes(mount.urlPath));
     try {
       await import_fs17.default.promises.mkdir(dest, { recursive: true });
       await import_fs17.default.promises.cp(mount.directory, dest, {
@@ -11992,7 +12007,7 @@ async function copyFastAPIStaticMounts(mounts, outputStaticDir) {
         force: false,
         filter: (_src, destPath) => {
           const urlPath = cdnUrlPath(outputStaticDir, destPath);
-          return !higherPriority.some((base) => mountCovers(base, urlPath));
+          return !higherPriority.some((base) => mountCovers(base, urlPath)) && !excluded.has(urlPath);
         }
       });
       copied.push(mount);
@@ -12008,9 +12023,33 @@ var MAX_ROUTE_SRC_LENGTH = 4096;
 function shadowSrc(bodies) {
   return `^/((?:${bodies.join("|")})/?)$`;
 }
+function redirectSrc(bodies) {
+  return `^/((?:${bodies.join("|")}))$`;
+}
 var SHADOW_SRC_WRAPPER_LENGTH = shadowSrc([]).length;
+var REDIRECT_SRC_WRAPPER_LENGTH = redirectSrc([]).length;
+function chunkBodies(bodies, wrapperLength) {
+  const chunks = [];
+  let srcLen = 0;
+  let dropped = 0;
+  for (const body of bodies) {
+    if (wrapperLength + body.length > MAX_ROUTE_SRC_LENGTH) {
+      dropped += 1;
+      continue;
+    }
+    const current = chunks[chunks.length - 1];
+    if (current && srcLen + 1 + body.length <= MAX_ROUTE_SRC_LENGTH) {
+      current.push(body);
+      srcLen += 1 + body.length;
+    } else {
+      chunks.push([body]);
+      srcLen = wrapperLength + body.length;
+    }
+  }
+  return { chunks, dropped };
+}
 async function runFastAPICollectStatic(venvPath, workPath, env, outputStaticDir, entrypointAbs, variableName, suppressMiddlewareMounts = true) {
-  const { mounts, shadowRoutes } = await getFastAPIStaticDiscovery(
+  const { mounts, shadowRoutes, excludedFiles } = await getFastAPIStaticDiscovery(
     venvPath,
     entrypointAbs,
     variableName,
@@ -12025,7 +12064,11 @@ async function runFastAPICollectStatic(venvPath, workPath, env, outputStaticDir,
   (0, import_build_utils20.debug)(
     `Found ${mounts.length} FastAPI static mount(s): ${mounts.map((m) => m.urlPath).join(", ")}`
   );
-  const copiedMounts = await copyFastAPIStaticMounts(mounts, outputStaticDir);
+  const copiedMounts = await copyFastAPIStaticMounts(
+    mounts,
+    outputStaticDir,
+    excludedFiles
+  );
   if (copiedMounts.length === 0) {
     return null;
   }
@@ -12033,6 +12076,7 @@ async function runFastAPICollectStatic(venvPath, workPath, env, outputStaticDir,
     collectedMounts: mounts,
     cdnOutputDir: outputStaticDir,
     shadowRoutes,
+    excludedFiles,
     // Only copied mounts get a fallback: a check:true dest that is missing makes
     // the proxy exit with the status instead of reaching the Lambda.
     fallbacks: copiedMounts.flatMap(
@@ -12055,22 +12099,11 @@ function fastapiShadowingRoutes(discovery, lambdaPath) {
   let dropped = 0;
   for (const [methodsKey, bodies] of byMethods) {
     const methods = methodsKey === "" ? void 0 : JSON.parse(methodsKey);
-    const chunks = [];
-    let srcLen = 0;
-    for (const body of bodies) {
-      if (SHADOW_SRC_WRAPPER_LENGTH + body.length > MAX_ROUTE_SRC_LENGTH) {
-        dropped += 1;
-        continue;
-      }
-      const current = chunks[chunks.length - 1];
-      if (current && srcLen + 1 + body.length <= MAX_ROUTE_SRC_LENGTH) {
-        current.push(body);
-        srcLen += 1 + body.length;
-      } else {
-        chunks.push([body]);
-        srcLen = SHADOW_SRC_WRAPPER_LENGTH + body.length;
-      }
-    }
+    const { chunks, dropped: d } = chunkBodies(
+      bodies,
+      SHADOW_SRC_WRAPPER_LENGTH
+    );
+    dropped += d;
     for (const chunk of chunks) {
       routes.push({
         src: shadowSrc(chunk),
@@ -12132,46 +12165,79 @@ function fastapiFallbackRoutes(discovery) {
   });
 }
 function getFastAPICdnBundle(collectedMounts, workPath, fastapiConfig) {
-  if (fastapiConfig?.static?.exclude !== true)
-    return { excludePatterns: [], directoryStubs: {}, redirects: [] };
+  const redirects = [];
   const excludePatterns = [];
   const directoryStubs = {};
-  const redirects = [];
-  for (const mount of collectedMounts) {
-    const relDir = (0, import_path17.relative)(workPath, mount.directory);
-    if (!relDir || relDir.startsWith("..") || (0, import_path17.isAbsolute)(relDir))
+  let redirectDropped = 0;
+  const higherPriority = [];
+  for (const mount of byCopyPriority(collectedMounts)) {
+    if (!mount.html && !mount.frontend) {
+      higherPriority.push(trimTrailingSlashes(mount.urlPath));
       continue;
-    const relDirUnix = relDir.split(import_path17.sep).join("/");
-    excludePatterns.push(`${relDirUnix}/**`);
-    directoryStubs[`${relDirUnix}/.static-placeholder`] = new import_build_utils20.FileBlob({
-      data: ""
-    });
-    for (const fallbackFile of ["index.html", "404.html"]) {
-      const fsPath = (0, import_path17.join)(mount.directory, fallbackFile);
-      if (import_fs17.default.existsSync(fsPath)) {
-        directoryStubs[`${relDirUnix}/${fallbackFile}`] = new import_build_utils20.FileFsRef({
-          fsPath
-        });
+    }
+    const urlPrefix = trimSlashes(mount.urlPath);
+    const bodies = [];
+    const collectBodies = (absDir, urlPath) => {
+      if (higherPriority.some((base) => mountCovers(base, `/${urlPath}`))) {
+        return;
+      }
+      if (urlPath && import_fs17.default.existsSync((0, import_path17.join)(absDir, "index.html"))) {
+        bodies.push(escapeRegex(urlPath));
       }
+      for (const entry of import_fs17.default.readdirSync(absDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+          continue;
+        collectBodies(
+          (0, import_path17.join)(absDir, entry.name),
+          urlPath ? `${urlPath}/${entry.name}` : entry.name
+        );
+      }
+    };
+    try {
+      collectBodies(mount.directory, urlPrefix);
+    } catch (err) {
+      (0, import_build_utils20.debug)(
+        `FastAPI: skipping bare-dir redirects for ${mount.urlPath} (${err})`
+      );
     }
-    if (mount.frontend) {
-      const urlPrefix = mount.urlPath.replace(/^\/+|\/+$/g, "");
-      const addBareRedirects = (absDir) => {
-        for (const entry of import_fs17.default.readdirSync(absDir, { withFileTypes: true })) {
-          if (!entry.isDirectory())
-            continue;
-          const subAbs = (0, import_path17.join)(absDir, entry.name);
-          const subPath = (0, import_path17.relative)(mount.directory, subAbs).split(import_path17.sep).join("/");
-          const urlPath = urlPrefix ? `${urlPrefix}/${subPath}` : subPath;
-          redirects.push({
-            src: `^/${escapeRegex(urlPath)}$`,
-            dest: `/${urlPath}/`,
-            status: 307
+    higherPriority.push(trimTrailingSlashes(mount.urlPath));
+    const { chunks, dropped } = chunkBodies(
+      bodies,
+      REDIRECT_SRC_WRAPPER_LENGTH
+    );
+    redirectDropped += dropped;
+    for (const chunk of chunks) {
+      redirects.push({
+        src: redirectSrc(chunk),
+        dest: "/$1/",
+        status: 307,
+        methods: ["GET", "HEAD"]
+      });
+    }
+  }
+  if (redirectDropped > 0) {
+    (0, import_build_utils20.debug)(
+      `FastAPI: ${redirectDropped} redirect(s) over the ${MAX_ROUTE_SRC_LENGTH} char cap left unredirected`
+    );
+  }
+  if (fastapiConfig?.static?.exclude === true) {
+    for (const mount of collectedMounts) {
+      const relDir = (0, import_path17.relative)(workPath, mount.directory);
+      if (!relDir || relDir.startsWith("..") || (0, import_path17.isAbsolute)(relDir))
+        continue;
+      const relDirUnix = relDir.split(import_path17.sep).join("/");
+      excludePatterns.push(`${relDirUnix}/**`);
+      directoryStubs[`${relDirUnix}/.static-placeholder`] = new import_build_utils20.FileBlob({
+        data: ""
+      });
+      for (const fallbackFile of ["index.html", "404.html"]) {
+        const fsPath = (0, import_path17.join)(mount.directory, fallbackFile);
+        if (import_fs17.default.existsSync(fsPath)) {
+          directoryStubs[`${relDirUnix}/${fallbackFile}`] = new import_build_utils20.FileFsRef({
+            fsPath
           });
-          addBareRedirects(subAbs);
         }
-      };
-      addBareRedirects(mount.directory);
+      }
     }
   }
   return { excludePatterns, directoryStubs, redirects };
@@ -14369,8 +14435,8 @@ var build = async ({
   const shadowingRoutes = fastapiStatic ? fastapiShadowingRoutes(fastapiStatic, lambdaPath) : [];
   const fallbackRoutes = fastapiStatic ? fastapiFallbackRoutes(fastapiStatic) : [];
   const routes = isNonWebService || !output ? queueRoutes.length > 0 ? queueRoutes : void 0 : [
-    ...cdnBundle.redirects,
     ...shadowingRoutes,
+    ...cdnBundle.redirects,
     { handle: "filesystem" },
     ...queueRoutes,
     ...fallbackRoutes.length > 0 ? [{ handle: "miss" }, ...fallbackRoutes] : [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/python",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "main": "./dist/index.js",
   "license": "Apache-2.0",
   "homepage": "https://vercel.com/docs/runtimes#official-runtimes/python",
@@ -39,8 +39,8 @@
     "vitest": "4.1.10",
     "which": "3.0.0",
     "@vercel/error-utils": "2.2.1",
-    "@vercel/python-runtime": "0.23.0",
-    "@vercel/build-utils": "14.10.1"
+    "@vercel/build-utils": "14.10.1",
+    "@vercel/python-runtime": "0.23.0"
   },
   "scripts": {
     "build": "node ../../utils/build-builder.mjs",

package/templates/vc_fastapi_static.py

@@ -6,24 +6,35 @@ Writes a JSON object to the output file:
 
     {
       "mounts": [
-        {"urlPath": str, "directory": str,
-         "fallback": {"file": str, "status": int} | null,
-         "frontend": bool}
+        {
+          "urlPath": str,
+          "directory": str,
+          "fallback": {"file": str, "status": int} | null,
+          "frontend": bool,
+          "html": bool
+        },
+        ...
       ],
-      "shadowRoutes": [str, ...]
+      "shadowRoutes": [
+        {"body": str, "methods": [str] | null},
+        ...
+      ],
+      "excludedFiles": [str, ...]
     }
 
-- "mounts" are StaticFiles / frontend directories to copy to the CDN;
+- "mounts" are StaticFiles / frontend directories to copy to the CDN.
   "frontend" marks a low-priority app.frontend() build.
-- "mounts[].fallback" is the resolved frontend fallback file to serve for
+  "html" reflects the StaticFiles html mode (always True for frontends).
+  "mounts[].fallback" is the resolved frontend fallback file to serve for
   unmatched paths under that mount ("index.html"/"404.html"), or null for a
-  plain `app.mount(StaticFiles(...))`.
-- "shadowRoutes" are routing patterns (regex bodies, matched against the request
-  path minus its leading slash) for paths a higher-priority route owns and that
-  must therefore be routed to the app (Lambda) BEFORE the CDN. This preserves
-  FastAPI precedence:
-    * app.mount():   routes declared BEFORE the mount win (evaluated in order).
-    * app.frontend(): all normal routes win (the build is low-priority).
+  plain app.mount(StaticFiles(...)).
+- "shadowRoutes" are pre-filesystem routing rules for paths that must reach
+  the Lambda before the CDN can act. Each entry carries a regex body (matched
+  against the request path minus its leading slash) and the HTTP methods it
+  applies to (null means all methods).
+- "excludedFiles" are CDN URL paths (with leading slash) of files in plain
+  StaticFiles mounts that prior GET/HEAD app routes own. The builder withholds
+  these from CDN copying so the Lambda catch-all serves them directly.
 
 Mounts are suppressed (omitted from output) when the app or a mounted sub-app
 has user-defined middleware, because CDN-served files bypass the middleware
@@ -67,6 +78,7 @@ class StaticMount:
     directory: str
     fallback: Fallback | None = None
     frontend: bool = False
+    html: bool = False
 
     @classmethod
     def from_route(
@@ -86,6 +98,7 @@ class StaticMount:
             directory=os.path.abspath(str(directory)),
             fallback=_resolve_fallback(static_app),
             frontend=frontend,
+            html=static_app.html,
         )
 
 
@@ -196,7 +209,7 @@ def _index_subdir_shadows(url_prefix: str, directory: str) -> set[str]:
     return shadows
 
 
-def _divergent_url_shadows(mount: StaticMount, html: bool) -> list[ShadowRoute]:
+def _divergent_url_shadows(mount: StaticMount) -> list[ShadowRoute]:
     """Shadow routes for directory URLs the CDN and the app serve differently.
 
     When a directory holds an index.html, the app and the CDN serve that
@@ -213,15 +226,18 @@ def _divergent_url_shadows(mount: StaticMount, html: bool) -> list[ShadowRoute]:
     html=False shadows both forms. The app 404s both while the CDN serves the
     index, so both must reach the Lambda.
 
-    Directory redirects are GET-only: HEAD for bare dirs is handled by the
-    builder's CDN redirect routes placed before shadow routes.
+    Shadows are all-methods: the Lambda 404s HEAD just as it does GET, which
+    matches the real app. No CDN redirect routes are emitted for html=False
+    mounts, so HEAD must be intercepted by the shadow.
     """
+    if mount.html:
+        return []  # bare-dir 307 redirects are emitted as static CDN rules by the builder
     bodies = _index_subdir_shadows(mount.urlPath, mount.directory)
-    if not (html and mount.urlPath == "/"):
+    # Only needed when index.html is present at the root. Without it the
+    # CDN has no implicit directory index to serve and misses naturally.
+    if os.path.isfile(os.path.join(mount.directory, "index.html")):
         bodies.add(_escape_path(mount.urlPath))
-    if html:
-        bodies = {f"{body}(?!/)" for body in bodies}
-    return [ShadowRoute(body=body, methods=("GET",)) for body in bodies]
+    return [ShadowRoute(body=body, methods=None) for body in bodies]
 
 
 def _frontend_groups(router: Router) -> list[_FrontendRouteGroup]:
@@ -338,6 +354,11 @@ class PriorRoute:
         parts.append(_escape(path[last:]))
         return "".join(parts)
 
+    @cached_property
+    def parametrized(self) -> bool:
+        """True when the path has `{param}` placeholders that expand to regex groups."""
+        return bool(_PARAM_RE.search(self.path_format))
+
 
 @dataclass
 class Precedence:
@@ -366,19 +387,18 @@ class Precedence:
     def shadow_bodies(self, mount: StaticMount) -> list[ShadowRoute]:
         """Shadow-route body+methods for every prior route that shadows `mount`.
 
-        When a route declares GET, HEAD is added to the shadow methods. HTTP
-        semantics tie HEAD to GET, so the Lambda (not the CDN) should handle
-        HEAD on API-owned paths and return 405 when HEAD is not declared.
+        Used for frontend mounts: the frontend fallback in handle: 'miss'
+        intercepts extension-less CDN misses and would serve index.html before
+        the Lambda catch-all is reached. A pre-filesystem shadow ensures the
+        Lambda handles these paths first.
         """
         result = []
         for r in self.routes:
             if not r.shadows(mount):
                 continue
             methods = r.methods
-            # With plain StaticFiles, HEAD bypasses the GET route and the
-            # mount serves it (200), so CDN can do the same without Lambda.
-            # With app.frontend(), HEAD on a GET route path returns 405.
-            # Shadow HEAD only for frontend mounts.
+            # HEAD on a GET-only route under a frontend returns 405 not 200,
+            # so the Lambda must handle it rather than the CDN.
             if methods is not None and "GET" in methods and mount.frontend:
                 methods = methods | {"HEAD"}
             result.append(
@@ -389,6 +409,162 @@ class Precedence:
             )
         return result
 
+    def excluded_files(self, mount: StaticMount) -> set[str]:
+        """CDN URL paths of files in `mount` that prior routes own.
+
+        Returns URL paths to exclude from the CDN so the Lambda serves them.
+        """
+        relevant = [
+            r for r in self.routes
+            if r.shadows(mount)
+            # Routes with no GET/HEAD methods leave their files on the CDN.
+            and (r.methods is None or r.methods & {"GET", "HEAD"})
+            # A trailing-slash route owns only the slash form; the bare-form
+            # file stays on the CDN (see trailing_slash_shadows).
+            and not (r.path_format.endswith("/") and r.path_format != "/")
+        ]
+        if not relevant:
+            return set()
+
+        literal_routes: list[PriorRoute] = []
+        parametrized_bodies: list[str] = []
+        for r in relevant:
+            if r.parametrized:
+                parametrized_bodies.append(r.shadow_body)
+            else:
+                literal_routes.append(r)
+
+        excluded: set[str] = set()
+        mount_prefix = mount.urlPath.strip("/")
+
+        # Literal fast-path: check file existence directly from the route path.
+        for r in literal_routes:
+            rel = r.path_format[len(mount.urlPath.rstrip("/")) + 1:]
+            if os.path.isfile(os.path.join(mount.directory, *rel.split("/"))):
+                excluded.add(r.path_format)
+
+        # Parametrized: one combined-regex pass over the directory tree.
+        if parametrized_bodies:
+            combined = re.compile("^(?:" + "|".join(parametrized_bodies) + ")$")
+            for dirpath, _, filenames in os.walk(mount.directory):
+                for filename in filenames:
+                    rel = os.path.relpath(
+                        os.path.join(dirpath, filename), mount.directory
+                    ).replace(os.sep, "/")
+                    url_body = f"{mount_prefix}/{rel}".lstrip("/")
+                    if combined.match(url_body):
+                        excluded.add("/" + url_body)
+
+        return excluded
+
+    def trailing_slash_shadows(self, mount: StaticMount) -> list[ShadowRoute]:
+        """Slash-form shadows for trailing-slash routes whose bare path is a file.
+
+        A route declared as @app.get("/mount/file/") owns the slash form of a
+        path where a file sits at the bare form on the CDN. The file stays on
+        the CDN; a slash-form shadow routes /mount/file/ to the Lambda before
+        the CDN can serve it.
+
+        A parametrized trailing-slash route owns the slash form of every path
+        it matches, so its whole pattern is shadowed with no file check: slash
+        forms without an underlying CDN file miss to the Lambda anyway, so the
+        broad shadow only pre-empts paths the Lambda already owns.
+        """
+        result = []
+        prefix_len = len(mount.urlPath.rstrip("/")) + 1
+        for r in self.routes:
+            if not r.shadows(mount):
+                continue
+            if not r.path_format.endswith("/") or r.path_format == "/":
+                continue
+            if r.parametrized:
+                result.append(ShadowRoute(body=r.shadow_body + "/", methods=None))
+                continue
+            rel = r.path_format[prefix_len:].rstrip("/")
+            if not rel:
+                continue
+            if os.path.isfile(os.path.join(mount.directory, *rel.split("/"))):
+                result.append(ShadowRoute(body=r.shadow_body + "/", methods=None))
+        return result
+
+    def non_cdn_method_shadows(self, mount: StaticMount) -> list[ShadowRoute]:
+        """Method-scoped shadows for prior routes with no GET/HEAD methods.
+
+        Such a route's colliding file stays on the CDN (see `excluded_files`),
+        but the CDN matches an existing file for any method and terminates
+        with 405 rather than falling through to the Lambda. Shadowing the
+        route's declared methods sends them to the app, which serves the
+        route. GET/HEAD stays on the CDN.
+        """
+        return [
+            ShadowRoute(body=r.shadow_body, methods=tuple(sorted(r.methods)))
+            for r in self.routes
+            if r.shadows(mount)
+            and r.methods is not None
+            and not (r.methods & {"GET", "HEAD"})
+        ]
+
+    def owned_dir_url_paths(self, mount: StaticMount) -> tuple[set[str], set[str]]:
+        """Directory URL paths in `mount` that prior GET/HEAD routes own.
+
+        For html=True mounts the CDN emits bare-dir 307 redirects for every
+        directory that has an index.html and serves the index at the slash
+        form. A prior route that owns the bare directory URL must be shadowed
+        so the Lambda handles the request before the redirect fires. A route
+        declared with a trailing slash owns the slash form instead (the app
+        307s the bare form to it), so that form must reach the Lambda before
+        the CDN serves the index.
+
+        Returns (bare_owned, slash_owned) directory URL paths.
+        """
+        relevant = [
+            r for r in self.routes
+            if r.shadows(mount)
+            and (r.methods is None or r.methods & {"GET", "HEAD"})
+        ]
+        if not relevant:
+            return set(), set()
+
+        bare_literal: set[str] = set()
+        slash_literal: set[str] = set()
+        bare_bodies: list[str] = []
+        slash_bodies: list[str] = []
+        for r in relevant:
+            slash_form = r.path_format.endswith("/") and r.path_format != "/"
+            if r.parametrized:
+                (slash_bodies if slash_form else bare_bodies).append(r.shadow_body)
+            else:
+                (slash_literal if slash_form else bare_literal).add(
+                    r.path_format.rstrip("/") or "/"
+                )
+
+        def _combined(bodies: list[str]) -> re.Pattern[str] | None:
+            return re.compile("^(?:" + "|".join(bodies) + ")$") if bodies else None
+
+        bare_combined = _combined(bare_bodies)
+        slash_combined = _combined(slash_bodies)
+
+        mount_prefix = mount.urlPath.strip("/")
+        bare_owned: set[str] = set()
+        slash_owned: set[str] = set()
+
+        for dirpath, _, filenames in os.walk(mount.directory):
+            if "index.html" not in filenames:
+                continue
+            rel = os.path.relpath(dirpath, mount.directory)
+            dir_url = (
+                mount.urlPath.rstrip("/") or "/"
+                if rel == "."
+                else mount.urlPath.rstrip("/") + "/" + rel.replace(os.sep, "/")
+            )
+            url_body = (mount_prefix + "/" + rel.replace(os.sep, "/")).lstrip("/") if rel != "." else mount_prefix
+            if dir_url in bare_literal or (bare_combined and bare_combined.match(url_body)):
+                bare_owned.add(dir_url)
+            if dir_url in slash_literal or (slash_combined and slash_combined.match(url_body)):
+                slash_owned.add(dir_url)
+
+        return bare_owned, slash_owned
+
     def add_mount(self, url_prefix: str) -> None:
         self.mount_prefixes.append(url_prefix.rstrip("/"))
 
@@ -410,25 +586,40 @@ def _collect_mount(
     *,
     has_middleware: bool,
     suppress_middleware_mounts: bool,
-) -> tuple[list[StaticMount], list[ShadowRoute]]:
+) -> tuple[list[StaticMount], list[ShadowRoute], list[str]]:
     """Discover one app.mount(): a StaticFiles mount serves from the CDN, a
     Router/sub-app recurses, and a raw ASGI app owns its subtree opaquely.
     """
     url_prefix = prefix + route.path
     if prior.eclipses(url_prefix):
-        return [], []
+        return [], [], []
 
     if suppress_middleware_mounts:
         has_middleware = has_middleware or bool(getattr(route.app, "user_middleware", []))
 
     mounts: list[StaticMount] = []
     shadow_routes: list[ShadowRoute] = []
+    excluded_files: set[str] = set()
 
     static = StaticMount.from_route(route, prefix, frontend=False)
     if static and not has_middleware:
         mounts.append(static)
-        shadow_routes += prior.shadow_bodies(static)
-        shadow_routes += _divergent_url_shadows(static, html=route.app.html)
+        excluded_files |= prior.excluded_files(static)
+        shadow_routes += prior.non_cdn_method_shadows(static)
+        shadow_routes += prior.trailing_slash_shadows(static)
+        shadow_routes += _divergent_url_shadows(static)
+        if route.app.html:
+            bare_owned, slash_owned = prior.owned_dir_url_paths(static)
+            for dir_url in bare_owned:
+                shadow_routes.append(
+                    ShadowRoute(body=_escape_path(dir_url) + "(?!/)", methods=None)
+                )
+            for dir_url in slash_owned:
+                # The trailing slash pins the builder's `^/((<body>)/?)$` wrap
+                # to the slash form only; the bare form stays on the CDN 307.
+                shadow_routes.append(
+                    ShadowRoute(body=_escape_path(dir_url) + "/", methods=None)
+                )
 
     # A Starlette/FastAPI sub-app isn't a Router but exposes one as `.router`;
     # a StaticFiles or raw ASGI app exposes neither.
@@ -441,7 +632,7 @@ def _collect_mount(
         # Recurse for the sub-app's own StaticFiles mounts, then shadow the
         # rest of its subtree to the Lambda.
         sub_prefix = prefix + route.path.rstrip("/")
-        sub_mounts, sub_shadow = collect(
+        sub_mounts, sub_shadow, sub_excluded = collect(
             sub_router,
             sub_prefix,
             prior,
@@ -450,6 +641,7 @@ def _collect_mount(
         )
         mounts.extend(sub_mounts)
         shadow_routes += sub_shadow
+        excluded_files.update(sub_excluded)
         shadow_routes.append(_subtree_shadow_route(sub_prefix, sub_mounts))
     elif static is None:
         # A raw ASGI app (e.g. WSGIMiddleware) owns its subtree with nothing on
@@ -458,7 +650,7 @@ def _collect_mount(
         shadow_routes.append(_subtree_shadow_route(url_prefix, []))
 
     prior.add_mount(url_prefix)
-    return mounts, shadow_routes
+    return mounts, shadow_routes, sorted(excluded_files)
 
 
 def collect(
@@ -468,16 +660,21 @@ def collect(
     *,
     has_middleware: bool,
     suppress_middleware_mounts: bool,
-) -> tuple[list[StaticMount], list[ShadowRoute]]:
-    """Walk the route table for (static mounts to copy, shadow routes).
+) -> tuple[list[StaticMount], list[ShadowRoute], list[str]]:
+    """Walk the route table for (static mounts to copy, shadow routes, excluded files).
 
     Shadow routes are merged so that the same path covered by multiple API
     routes with different methods produces one entry with the union of methods.
+
+    Excluded files are CDN URL paths withheld from copying so the Lambda
+    catch-all serves them directly. Covers plain StaticFiles app-route-wins
+    only.
     """
     prior = prior.child() if prior else Precedence()
 
     mounts: list[StaticMount] = []
     shadow_routes: list[ShadowRoute] = []
+    excluded_files: set[str] = set()
     frontends: list[StaticMount] = []
 
     def _route_methods(route: Route) -> frozenset[str] | None:
@@ -486,13 +683,14 @@ def collect(
         return frozenset(m) if m else None
 
     def collect_mount(mount_route: Mount) -> None:
-        sub_mounts, sub_shadow = _collect_mount(
+        sub_mounts, sub_shadow, sub_excluded = _collect_mount(
             mount_route, prefix, prior,
             has_middleware=has_middleware,
             suppress_middleware_mounts=suppress_middleware_mounts,
         )
         mounts.extend(sub_mounts)
         shadow_routes.extend(sub_shadow)
+        excluded_files.update(sub_excluded)
 
     for route in router.routes:
         if isinstance(route, Route):
@@ -563,10 +761,8 @@ def collect(
             continue
         mounts.append(m)
         shadow_routes += prior.shadow_bodies(m)
-        # A frontend is html=True StaticFiles, so its URLs diverge the same way.
-        shadow_routes += _divergent_url_shadows(m, html=True)
 
-    return mounts, _merge_shadow_routes(shadow_routes)
+    return mounts, _merge_shadow_routes(shadow_routes), sorted(excluded_files)
 
 
 def _merge_shadow_routes(routes: list[ShadowRoute]) -> list[ShadowRoute]:
@@ -611,11 +807,13 @@ class Output:
 
     mounts: list[StaticMount] = field(default_factory=list)
     shadowRoutes: list[ShadowRoute] = field(default_factory=list)
+    excludedFiles: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, object]:
         return {
             "mounts": [asdict(m) for m in self.mounts],
             "shadowRoutes": [sr.to_dict() for sr in self.shadowRoutes],
+            "excludedFiles": list(self.excludedFiles),
         }
 
 
@@ -651,10 +849,10 @@ def discover(variable_name: str, project_root: str, module_name: str, suppress_m
     if suppress_middleware_mounts and getattr(app, "user_middleware", []):
         return Output()
 
-    mounts, shadow_routes = collect(
+    mounts, shadow_routes, excluded_files = collect(
         router, has_middleware=False, suppress_middleware_mounts=suppress_middleware_mounts
     )
-    return Output(mounts=mounts, shadowRoutes=shadow_routes)
+    return Output(mounts=mounts, shadowRoutes=shadow_routes, excludedFiles=excluded_files)
 
 
 def main() -> None: