qlara 0.1.10 → 0.1.12

package/dist/aws.cjs

@@ -462,8 +462,25 @@ function buildTemplate(config) {
                   }
                 }
               ]
-            }
-            // No CustomErrorResponses — the edge handler manages 403/404
+            },
+            // Serve the framework's 404 page (e.g., Next.js not-found.ts → 404.html)
+            // when S3 returns 403 (missing file) or 404. This covers:
+            // - Unknown routes not in the manifest
+            // - Validation failures (renderer abandons, no file uploaded)
+            CustomErrorResponses: [
+              {
+                ErrorCode: 403,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              },
+              {
+                ErrorCode: 404,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              }
+            ]
           }
         }
       }
@@ -599,7 +616,9 @@ var STACK_NAME_PREFIX = "qlara";
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
 var FALLBACK_FILENAME = "_fallback.html";
-var FALLBACK_PLACEHOLDER = "__QLARA_FALLBACK__";
+function paramPlaceholder(paramName) {
+  return `__QLARA_FALLBACK_${paramName}__`;
+}
 function generateFallbackFromTemplate(templateHtml, routePattern) {
   let fallback = templateHtml;
   const paramNames = (routePattern.match(/:([^/]+)/g) || []).map((m) => m.slice(1));
@@ -622,7 +641,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -632,20 +651,30 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       segmentRegex,
-      `[\\"${param}\\",\\"${FALLBACK_PLACEHOLDER}\\",\\"d\\"]`
+      `[\\"${param}\\",\\"${paramPlaceholder(param)}\\",\\"d\\"]`
     );
   }
-  const routeParts = routePattern.split("/").filter((p) => !p.startsWith(":"));
-  if (routeParts.length > 0) {
-    const prefix = routeParts.map((p) => `${q}${p}${q}`).join(",");
-    const urlSegmentRegex = new RegExp(
-      `(${q}c${q}:\\[${prefix},)${q}[^"]*${q}\\]`,
+  const allSegments = routePattern.split("/");
+  if (allSegments.length > 1) {
+    const regexParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        return `${q}[^"]*${q}`;
+      }
+      return `${q}${seg}${q}`;
+    });
+    const cArrayRegex = new RegExp(
+      `(${q}c${q}:\\[)${regexParts.join(",")}(\\])`,
       "g"
     );
-    fallback = fallback.replace(
-      urlSegmentRegex,
-      `$1\\"${FALLBACK_PLACEHOLDER}\\"]`
-    );
+    const replacementParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        const pName = seg.slice(1);
+        return `\\"${paramPlaceholder(pName)}\\"`;
+      }
+      return `\\"${seg}\\"`;
+    });
+    const replacement = `$1${replacementParts.join(",")}$2`;
+    fallback = fallback.replace(cArrayRegex, replacement);
   }
   fallback = fallback.replace(
     /8:\{\\"metadata\\":\[[\s\S]*?\],\\"error\\":null,\\"digest\\":\\"?\$undefined\\?"\}/,
@@ -653,33 +682,55 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
   );
   return fallback;
 }
+function findTemplateForRoute(buildDir, routePattern) {
+  const segments = routePattern.replace(/^\//, "").split("/");
+  function walk(currentDir, segmentIndex) {
+    if (segmentIndex >= segments.length) return null;
+    if (!(0, import_node_fs3.existsSync)(currentDir)) return null;
+    const segment = segments[segmentIndex];
+    const isLast = segmentIndex === segments.length - 1;
+    const isDynamic = segment.startsWith(":");
+    if (isLast) {
+      const files = (0, import_node_fs3.readdirSync)(currentDir).filter(
+        (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
+      );
+      return files.length > 0 ? (0, import_node_path3.join)(currentDir, files[0]) : null;
+    }
+    if (isDynamic) {
+      const entries = (0, import_node_fs3.readdirSync)(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith("_") && !entry.name.startsWith(".")) {
+          const result = walk((0, import_node_path3.join)(currentDir, entry.name), segmentIndex + 1);
+          if (result) return result;
+        }
+      }
+      return null;
+    }
+    return walk((0, import_node_path3.join)(currentDir, segment), segmentIndex + 1);
+  }
+  return walk(buildDir, 0);
+}
 function generateFallbacks(buildDir, routes) {
   const generated = [];
   for (const route of routes) {
-    const parts = route.pattern.replace(/^\//, "").split("/");
-    const dirParts = parts.filter((p) => !p.startsWith(":"));
-    const routeDir = (0, import_node_path3.join)(buildDir, ...dirParts);
-    if (!(0, import_node_fs3.existsSync)(routeDir)) {
+    const templatePath = findTemplateForRoute(buildDir, route.pattern);
+    if (!templatePath) {
       console.warn(
-        `[qlara] Warning: No output directory for route ${route.pattern} at ${routeDir}`
+        `[qlara] Warning: No HTML template found for route ${route.pattern}`
       );
       continue;
     }
-    const files = (0, import_node_fs3.readdirSync)(routeDir).filter(
-      (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
-    );
-    if (files.length === 0) {
-      console.warn(
-        `[qlara] Warning: No HTML files in ${routeDir} to create fallback template`
-      );
-      continue;
-    }
-    const templatePath = (0, import_node_path3.join)(routeDir, files[0]);
     const templateHtml = (0, import_node_fs3.readFileSync)(templatePath, "utf-8");
     const fallbackHtml = generateFallbackFromTemplate(templateHtml, route.pattern);
-    const fallbackPath = (0, import_node_path3.join)(routeDir, FALLBACK_FILENAME);
+    const parts = route.pattern.replace(/^\//, "").split("/");
+    const dirParts = parts.filter((p) => !p.startsWith(":"));
+    const fallbackDir = dirParts.length > 0 ? (0, import_node_path3.join)(buildDir, ...dirParts) : buildDir;
+    if (!(0, import_node_fs3.existsSync)(fallbackDir)) {
+      (0, import_node_fs3.mkdirSync)(fallbackDir, { recursive: true });
+    }
+    const fallbackPath = (0, import_node_path3.join)(fallbackDir, FALLBACK_FILENAME);
     (0, import_node_fs3.writeFileSync)(fallbackPath, fallbackHtml);
-    const relativePath = (0, import_node_path3.join)(...dirParts, FALLBACK_FILENAME);
+    const relativePath = dirParts.length > 0 ? (0, import_node_path3.join)(...dirParts, FALLBACK_FILENAME) : FALLBACK_FILENAME;
     generated.push(relativePath);
     console.log(`[qlara] Generated fallback: ${relativePath}`);
   }
@@ -777,6 +828,18 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
     const qlaraPolicyId = await ensureCachePolicy(cf);
     config.DefaultCacheBehavior.CachePolicyId = qlaraPolicyId;
   }
+  const hasErrorResponses = config.CustomErrorResponses?.Items?.some(
+    (r) => r.ErrorCode === 403
+  );
+  if (!hasErrorResponses) {
+    config.CustomErrorResponses = {
+      Quantity: 2,
+      Items: [
+        { ErrorCode: 403, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 },
+        { ErrorCode: 404, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 }
+      ]
+    };
+  }
   await cf.send(
     new import_client_cloudfront.UpdateDistributionCommand({
       Id: distributionId,

package/dist/aws.d.cts

@@ -1,4 +1,4 @@
-import { P as ProviderResources, Q as QlaraProvider } from './types--KPPgCtc.cjs';
+import { P as ProviderResources, Q as QlaraProvider } from './types-BmSR1R_Q.cjs';
 
 interface AwsConfig {
     stackName?: string;

package/dist/aws.d.ts

@@ -1,4 +1,4 @@
-import { P as ProviderResources, Q as QlaraProvider } from './types--KPPgCtc.js';
+import { P as ProviderResources, Q as QlaraProvider } from './types-BmSR1R_Q.js';
 
 interface AwsConfig {
     stackName?: string;

package/dist/aws.js

@@ -459,8 +459,25 @@ function buildTemplate(config) {
                   }
                 }
               ]
-            }
-            // No CustomErrorResponses — the edge handler manages 403/404
+            },
+            // Serve the framework's 404 page (e.g., Next.js not-found.ts → 404.html)
+            // when S3 returns 403 (missing file) or 404. This covers:
+            // - Unknown routes not in the manifest
+            // - Validation failures (renderer abandons, no file uploaded)
+            CustomErrorResponses: [
+              {
+                ErrorCode: 403,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              },
+              {
+                ErrorCode: 404,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              }
+            ]
           }
         }
       }
@@ -592,10 +609,12 @@ async function bundleRenderer(routeFile, cacheTtl = 3600, framework) {
 var STACK_NAME_PREFIX = "qlara";
 
 // src/fallback.ts
-import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
 import { join as join3 } from "path";
 var FALLBACK_FILENAME = "_fallback.html";
-var FALLBACK_PLACEHOLDER = "__QLARA_FALLBACK__";
+function paramPlaceholder(paramName) {
+  return `__QLARA_FALLBACK_${paramName}__`;
+}
 function generateFallbackFromTemplate(templateHtml, routePattern) {
   let fallback = templateHtml;
   const paramNames = (routePattern.match(/:([^/]+)/g) || []).map((m) => m.slice(1));
@@ -618,7 +637,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -628,20 +647,30 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       segmentRegex,
-      `[\\"${param}\\",\\"${FALLBACK_PLACEHOLDER}\\",\\"d\\"]`
+      `[\\"${param}\\",\\"${paramPlaceholder(param)}\\",\\"d\\"]`
     );
   }
-  const routeParts = routePattern.split("/").filter((p) => !p.startsWith(":"));
-  if (routeParts.length > 0) {
-    const prefix = routeParts.map((p) => `${q}${p}${q}`).join(",");
-    const urlSegmentRegex = new RegExp(
-      `(${q}c${q}:\\[${prefix},)${q}[^"]*${q}\\]`,
+  const allSegments = routePattern.split("/");
+  if (allSegments.length > 1) {
+    const regexParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        return `${q}[^"]*${q}`;
+      }
+      return `${q}${seg}${q}`;
+    });
+    const cArrayRegex = new RegExp(
+      `(${q}c${q}:\\[)${regexParts.join(",")}(\\])`,
       "g"
     );
-    fallback = fallback.replace(
-      urlSegmentRegex,
-      `$1\\"${FALLBACK_PLACEHOLDER}\\"]`
-    );
+    const replacementParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        const pName = seg.slice(1);
+        return `\\"${paramPlaceholder(pName)}\\"`;
+      }
+      return `\\"${seg}\\"`;
+    });
+    const replacement = `$1${replacementParts.join(",")}$2`;
+    fallback = fallback.replace(cArrayRegex, replacement);
   }
   fallback = fallback.replace(
     /8:\{\\"metadata\\":\[[\s\S]*?\],\\"error\\":null,\\"digest\\":\\"?\$undefined\\?"\}/,
@@ -649,33 +678,55 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
   );
   return fallback;
 }
+function findTemplateForRoute(buildDir, routePattern) {
+  const segments = routePattern.replace(/^\//, "").split("/");
+  function walk(currentDir, segmentIndex) {
+    if (segmentIndex >= segments.length) return null;
+    if (!existsSync2(currentDir)) return null;
+    const segment = segments[segmentIndex];
+    const isLast = segmentIndex === segments.length - 1;
+    const isDynamic = segment.startsWith(":");
+    if (isLast) {
+      const files = readdirSync2(currentDir).filter(
+        (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
+      );
+      return files.length > 0 ? join3(currentDir, files[0]) : null;
+    }
+    if (isDynamic) {
+      const entries = readdirSync2(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith("_") && !entry.name.startsWith(".")) {
+          const result = walk(join3(currentDir, entry.name), segmentIndex + 1);
+          if (result) return result;
+        }
+      }
+      return null;
+    }
+    return walk(join3(currentDir, segment), segmentIndex + 1);
+  }
+  return walk(buildDir, 0);
+}
 function generateFallbacks(buildDir, routes) {
   const generated = [];
   for (const route of routes) {
-    const parts = route.pattern.replace(/^\//, "").split("/");
-    const dirParts = parts.filter((p) => !p.startsWith(":"));
-    const routeDir = join3(buildDir, ...dirParts);
-    if (!existsSync2(routeDir)) {
+    const templatePath = findTemplateForRoute(buildDir, route.pattern);
+    if (!templatePath) {
       console.warn(
-        `[qlara] Warning: No output directory for route ${route.pattern} at ${routeDir}`
+        `[qlara] Warning: No HTML template found for route ${route.pattern}`
       );
       continue;
     }
-    const files = readdirSync2(routeDir).filter(
-      (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
-    );
-    if (files.length === 0) {
-      console.warn(
-        `[qlara] Warning: No HTML files in ${routeDir} to create fallback template`
-      );
-      continue;
-    }
-    const templatePath = join3(routeDir, files[0]);
     const templateHtml = readFileSync3(templatePath, "utf-8");
     const fallbackHtml = generateFallbackFromTemplate(templateHtml, route.pattern);
-    const fallbackPath = join3(routeDir, FALLBACK_FILENAME);
+    const parts = route.pattern.replace(/^\//, "").split("/");
+    const dirParts = parts.filter((p) => !p.startsWith(":"));
+    const fallbackDir = dirParts.length > 0 ? join3(buildDir, ...dirParts) : buildDir;
+    if (!existsSync2(fallbackDir)) {
+      mkdirSync2(fallbackDir, { recursive: true });
+    }
+    const fallbackPath = join3(fallbackDir, FALLBACK_FILENAME);
     writeFileSync(fallbackPath, fallbackHtml);
-    const relativePath = join3(...dirParts, FALLBACK_FILENAME);
+    const relativePath = dirParts.length > 0 ? join3(...dirParts, FALLBACK_FILENAME) : FALLBACK_FILENAME;
     generated.push(relativePath);
     console.log(`[qlara] Generated fallback: ${relativePath}`);
   }
@@ -773,6 +824,18 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
     const qlaraPolicyId = await ensureCachePolicy(cf);
     config.DefaultCacheBehavior.CachePolicyId = qlaraPolicyId;
   }
+  const hasErrorResponses = config.CustomErrorResponses?.Items?.some(
+    (r) => r.ErrorCode === 403
+  );
+  if (!hasErrorResponses) {
+    config.CustomErrorResponses = {
+      Quantity: 2,
+      Items: [
+        { ErrorCode: 403, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 },
+        { ErrorCode: 404, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 }
+      ]
+    };
+  }
   await cf.send(
     new UpdateDistributionCommand({
       Id: distributionId,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync3 } from "fs";
 import { join as join4 } from "path";
 
 // src/provider/aws/constants.ts
@@ -470,8 +470,25 @@ function buildTemplate(config) {
                   }
                 }
               ]
-            }
-            // No CustomErrorResponses — the edge handler manages 403/404
+            },
+            // Serve the framework's 404 page (e.g., Next.js not-found.ts → 404.html)
+            // when S3 returns 403 (missing file) or 404. This covers:
+            // - Unknown routes not in the manifest
+            // - Validation failures (renderer abandons, no file uploaded)
+            CustomErrorResponses: [
+              {
+                ErrorCode: 403,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              },
+              {
+                ErrorCode: 404,
+                ResponseCode: 404,
+                ResponsePagePath: "/404.html",
+                ErrorCachingMinTTL: 10
+              }
+            ]
           }
         }
       }
@@ -600,10 +617,12 @@ async function bundleRenderer(routeFile, cacheTtl = 3600, framework) {
 }
 
 // src/fallback.ts
-import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
 import { join as join3 } from "path";
 var FALLBACK_FILENAME = "_fallback.html";
-var FALLBACK_PLACEHOLDER = "__QLARA_FALLBACK__";
+function paramPlaceholder(paramName) {
+  return `__QLARA_FALLBACK_${paramName}__`;
+}
 function generateFallbackFromTemplate(templateHtml, routePattern) {
   let fallback = templateHtml;
   const paramNames = (routePattern.match(/:([^/]+)/g) || []).map((m) => m.slice(1));
@@ -626,7 +645,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -636,20 +655,30 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       segmentRegex,
-      `[\\"${param}\\",\\"${FALLBACK_PLACEHOLDER}\\",\\"d\\"]`
+      `[\\"${param}\\",\\"${paramPlaceholder(param)}\\",\\"d\\"]`
     );
   }
-  const routeParts = routePattern.split("/").filter((p) => !p.startsWith(":"));
-  if (routeParts.length > 0) {
-    const prefix = routeParts.map((p) => `${q}${p}${q}`).join(",");
-    const urlSegmentRegex = new RegExp(
-      `(${q}c${q}:\\[${prefix},)${q}[^"]*${q}\\]`,
+  const allSegments = routePattern.split("/");
+  if (allSegments.length > 1) {
+    const regexParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        return `${q}[^"]*${q}`;
+      }
+      return `${q}${seg}${q}`;
+    });
+    const cArrayRegex = new RegExp(
+      `(${q}c${q}:\\[)${regexParts.join(",")}(\\])`,
       "g"
     );
-    fallback = fallback.replace(
-      urlSegmentRegex,
-      `$1\\"${FALLBACK_PLACEHOLDER}\\"]`
-    );
+    const replacementParts = allSegments.map((seg) => {
+      if (seg.startsWith(":")) {
+        const pName = seg.slice(1);
+        return `\\"${paramPlaceholder(pName)}\\"`;
+      }
+      return `\\"${seg}\\"`;
+    });
+    const replacement = `$1${replacementParts.join(",")}$2`;
+    fallback = fallback.replace(cArrayRegex, replacement);
   }
   fallback = fallback.replace(
     /8:\{\\"metadata\\":\[[\s\S]*?\],\\"error\\":null,\\"digest\\":\\"?\$undefined\\?"\}/,
@@ -657,33 +686,55 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
   );
   return fallback;
 }
+function findTemplateForRoute(buildDir, routePattern) {
+  const segments = routePattern.replace(/^\//, "").split("/");
+  function walk(currentDir, segmentIndex) {
+    if (segmentIndex >= segments.length) return null;
+    if (!existsSync2(currentDir)) return null;
+    const segment = segments[segmentIndex];
+    const isLast = segmentIndex === segments.length - 1;
+    const isDynamic = segment.startsWith(":");
+    if (isLast) {
+      const files = readdirSync2(currentDir).filter(
+        (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
+      );
+      return files.length > 0 ? join3(currentDir, files[0]) : null;
+    }
+    if (isDynamic) {
+      const entries = readdirSync2(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith("_") && !entry.name.startsWith(".")) {
+          const result = walk(join3(currentDir, entry.name), segmentIndex + 1);
+          if (result) return result;
+        }
+      }
+      return null;
+    }
+    return walk(join3(currentDir, segment), segmentIndex + 1);
+  }
+  return walk(buildDir, 0);
+}
 function generateFallbacks(buildDir, routes) {
   const generated = [];
   for (const route of routes) {
-    const parts = route.pattern.replace(/^\//, "").split("/");
-    const dirParts = parts.filter((p) => !p.startsWith(":"));
-    const routeDir = join3(buildDir, ...dirParts);
-    if (!existsSync2(routeDir)) {
+    const templatePath = findTemplateForRoute(buildDir, route.pattern);
+    if (!templatePath) {
       console.warn(
-        `[qlara] Warning: No output directory for route ${route.pattern} at ${routeDir}`
+        `[qlara] Warning: No HTML template found for route ${route.pattern}`
       );
       continue;
     }
-    const files = readdirSync2(routeDir).filter(
-      (f) => f.endsWith(".html") && f !== FALLBACK_FILENAME
-    );
-    if (files.length === 0) {
-      console.warn(
-        `[qlara] Warning: No HTML files in ${routeDir} to create fallback template`
-      );
-      continue;
-    }
-    const templatePath = join3(routeDir, files[0]);
     const templateHtml = readFileSync3(templatePath, "utf-8");
     const fallbackHtml = generateFallbackFromTemplate(templateHtml, route.pattern);
-    const fallbackPath = join3(routeDir, FALLBACK_FILENAME);
+    const parts = route.pattern.replace(/^\//, "").split("/");
+    const dirParts = parts.filter((p) => !p.startsWith(":"));
+    const fallbackDir = dirParts.length > 0 ? join3(buildDir, ...dirParts) : buildDir;
+    if (!existsSync2(fallbackDir)) {
+      mkdirSync2(fallbackDir, { recursive: true });
+    }
+    const fallbackPath = join3(fallbackDir, FALLBACK_FILENAME);
     writeFileSync(fallbackPath, fallbackHtml);
-    const relativePath = join3(...dirParts, FALLBACK_FILENAME);
+    const relativePath = dirParts.length > 0 ? join3(...dirParts, FALLBACK_FILENAME) : FALLBACK_FILENAME;
     generated.push(relativePath);
     console.log(`[qlara] Generated fallback: ${relativePath}`);
   }
@@ -781,6 +832,18 @@ async function updateCloudFrontEdgeVersion(cf, distributionId, newVersionArn) {
     const qlaraPolicyId = await ensureCachePolicy(cf);
     config.DefaultCacheBehavior.CachePolicyId = qlaraPolicyId;
   }
+  const hasErrorResponses = config.CustomErrorResponses?.Items?.some(
+    (r) => r.ErrorCode === 403
+  );
+  if (!hasErrorResponses) {
+    config.CustomErrorResponses = {
+      Quantity: 2,
+      Items: [
+        { ErrorCode: 403, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 },
+        { ErrorCode: 404, ResponseCode: "404", ResponsePagePath: "/404.html", ErrorCachingMinTTL: 10 }
+      ]
+    };
+  }
   await cf.send(
     new UpdateDistributionCommand({
       Id: distributionId,
@@ -1149,7 +1212,7 @@ function loadResources() {
   return JSON.parse(readFileSync4(RESOURCES_PATH, "utf-8"));
 }
 function saveResources(resources) {
-  mkdirSync2(QLARA_DIR, { recursive: true });
+  mkdirSync3(QLARA_DIR, { recursive: true });
   writeFileSync2(RESOURCES_PATH, JSON.stringify(resources, null, 2));
 }
 async function deploy() {

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { a as QlaraPluginConfig, b as QlaraRoute, c as QlaraManifest, M as ManifestRoute, R as RouteMatch } from './types--KPPgCtc.cjs';
-export { P as ProviderResources, d as QlaraAlternateLinkDescriptor, e as QlaraAlternateURLs, f as QlaraAppLinks, g as QlaraAppLinksAndroid, h as QlaraAppLinksApple, i as QlaraAppLinksWeb, j as QlaraAppLinksWindows, k as QlaraAppleImage, l as QlaraAppleImageDescriptor, m as QlaraAppleWebApp, n as QlaraAuthor, o as QlaraDeployConfig, p as QlaraFacebook, q as QlaraFormatDetection, r as QlaraIcon, s as QlaraIconDescriptor, t as QlaraIcons, u as QlaraItunesApp, v as QlaraMetaDataGenerator, w as QlaraMetadata, x as QlaraOGAudio, y as QlaraOGAudioDescriptor, z as QlaraOGImage, A as QlaraOGImageDescriptor, B as QlaraOGVideo, C as QlaraOGVideoDescriptor, D as QlaraOpenGraph, E as QlaraOpenGraphArticle, F as QlaraOpenGraphBase, G as QlaraOpenGraphBook, H as QlaraOpenGraphMusicAlbum, I as QlaraOpenGraphMusicPlaylist, J as QlaraOpenGraphMusicRadioStation, K as QlaraOpenGraphMusicSong, L as QlaraOpenGraphProfile, N as QlaraOpenGraphVideoEpisode, O as QlaraOpenGraphVideoMovie, S as QlaraOpenGraphVideoOther, T as QlaraOpenGraphVideoTVShow, U as QlaraOpenGraphWebsite, V as QlaraPinterest, Q as QlaraProvider, W as QlaraReferrer, X as QlaraRobots, Y as QlaraRobotsInfo, Z as QlaraRouteDefinition, _ as QlaraRoutes, $ as QlaraTwitter, a0 as QlaraTwitterApp, a1 as QlaraTwitterAppDescriptor, a2 as QlaraTwitterBase, a3 as QlaraTwitterImage, a4 as QlaraTwitterImageDescriptor, a5 as QlaraTwitterPlayer, a6 as QlaraTwitterPlayerDescriptor, a7 as QlaraTwitterSummary, a8 as QlaraTwitterSummaryLargeImage, a9 as QlaraVerification } from './types--KPPgCtc.cjs';
+import { a as QlaraPluginConfig, b as QlaraRoute, c as QlaraManifest, M as ManifestRoute, R as RouteMatch } from './types-BmSR1R_Q.cjs';
+export { P as ProviderResources, d as QlaraAlternateLinkDescriptor, e as QlaraAlternateURLs, f as QlaraAppLinks, g as QlaraAppLinksAndroid, h as QlaraAppLinksApple, i as QlaraAppLinksWeb, j as QlaraAppLinksWindows, k as QlaraAppleImage, l as QlaraAppleImageDescriptor, m as QlaraAppleWebApp, n as QlaraAuthor, o as QlaraDeployConfig, p as QlaraFacebook, q as QlaraFormatDetection, r as QlaraIcon, s as QlaraIconDescriptor, t as QlaraIcons, u as QlaraItunesApp, v as QlaraMetaDataGenerator, w as QlaraMetadata, x as QlaraOGAudio, y as QlaraOGAudioDescriptor, z as QlaraOGImage, A as QlaraOGImageDescriptor, B as QlaraOGVideo, C as QlaraOGVideoDescriptor, D as QlaraOpenGraph, E as QlaraOpenGraphArticle, F as QlaraOpenGraphBase, G as QlaraOpenGraphBook, H as QlaraOpenGraphMusicAlbum, I as QlaraOpenGraphMusicPlaylist, J as QlaraOpenGraphMusicRadioStation, K as QlaraOpenGraphMusicSong, L as QlaraOpenGraphProfile, N as QlaraOpenGraphVideoEpisode, O as QlaraOpenGraphVideoMovie, S as QlaraOpenGraphVideoOther, T as QlaraOpenGraphVideoTVShow, U as QlaraOpenGraphWebsite, V as QlaraPinterest, Q as QlaraProvider, W as QlaraReferrer, X as QlaraRobots, Y as QlaraRobotsInfo, Z as QlaraRouteDefinition, _ as QlaraRoutes, $ as QlaraTwitter, a0 as QlaraTwitterApp, a1 as QlaraTwitterAppDescriptor, a2 as QlaraTwitterBase, a3 as QlaraTwitterImage, a4 as QlaraTwitterImageDescriptor, a5 as QlaraTwitterPlayer, a6 as QlaraTwitterPlayerDescriptor, a7 as QlaraTwitterSummary, a8 as QlaraTwitterSummaryLargeImage, a9 as QlaraValidate, aa as QlaraVerification } from './types-BmSR1R_Q.cjs';
 
 declare function validateConfig(config: QlaraPluginConfig, routes: QlaraRoute[]): void;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as QlaraPluginConfig, b as QlaraRoute, c as QlaraManifest, M as ManifestRoute, R as RouteMatch } from './types--KPPgCtc.js';
-export { P as ProviderResources, d as QlaraAlternateLinkDescriptor, e as QlaraAlternateURLs, f as QlaraAppLinks, g as QlaraAppLinksAndroid, h as QlaraAppLinksApple, i as QlaraAppLinksWeb, j as QlaraAppLinksWindows, k as QlaraAppleImage, l as QlaraAppleImageDescriptor, m as QlaraAppleWebApp, n as QlaraAuthor, o as QlaraDeployConfig, p as QlaraFacebook, q as QlaraFormatDetection, r as QlaraIcon, s as QlaraIconDescriptor, t as QlaraIcons, u as QlaraItunesApp, v as QlaraMetaDataGenerator, w as QlaraMetadata, x as QlaraOGAudio, y as QlaraOGAudioDescriptor, z as QlaraOGImage, A as QlaraOGImageDescriptor, B as QlaraOGVideo, C as QlaraOGVideoDescriptor, D as QlaraOpenGraph, E as QlaraOpenGraphArticle, F as QlaraOpenGraphBase, G as QlaraOpenGraphBook, H as QlaraOpenGraphMusicAlbum, I as QlaraOpenGraphMusicPlaylist, J as QlaraOpenGraphMusicRadioStation, K as QlaraOpenGraphMusicSong, L as QlaraOpenGraphProfile, N as QlaraOpenGraphVideoEpisode, O as QlaraOpenGraphVideoMovie, S as QlaraOpenGraphVideoOther, T as QlaraOpenGraphVideoTVShow, U as QlaraOpenGraphWebsite, V as QlaraPinterest, Q as QlaraProvider, W as QlaraReferrer, X as QlaraRobots, Y as QlaraRobotsInfo, Z as QlaraRouteDefinition, _ as QlaraRoutes, $ as QlaraTwitter, a0 as QlaraTwitterApp, a1 as QlaraTwitterAppDescriptor, a2 as QlaraTwitterBase, a3 as QlaraTwitterImage, a4 as QlaraTwitterImageDescriptor, a5 as QlaraTwitterPlayer, a6 as QlaraTwitterPlayerDescriptor, a7 as QlaraTwitterSummary, a8 as QlaraTwitterSummaryLargeImage, a9 as QlaraVerification } from './types--KPPgCtc.js';
+import { a as QlaraPluginConfig, b as QlaraRoute, c as QlaraManifest, M as ManifestRoute, R as RouteMatch } from './types-BmSR1R_Q.js';
+export { P as ProviderResources, d as QlaraAlternateLinkDescriptor, e as QlaraAlternateURLs, f as QlaraAppLinks, g as QlaraAppLinksAndroid, h as QlaraAppLinksApple, i as QlaraAppLinksWeb, j as QlaraAppLinksWindows, k as QlaraAppleImage, l as QlaraAppleImageDescriptor, m as QlaraAppleWebApp, n as QlaraAuthor, o as QlaraDeployConfig, p as QlaraFacebook, q as QlaraFormatDetection, r as QlaraIcon, s as QlaraIconDescriptor, t as QlaraIcons, u as QlaraItunesApp, v as QlaraMetaDataGenerator, w as QlaraMetadata, x as QlaraOGAudio, y as QlaraOGAudioDescriptor, z as QlaraOGImage, A as QlaraOGImageDescriptor, B as QlaraOGVideo, C as QlaraOGVideoDescriptor, D as QlaraOpenGraph, E as QlaraOpenGraphArticle, F as QlaraOpenGraphBase, G as QlaraOpenGraphBook, H as QlaraOpenGraphMusicAlbum, I as QlaraOpenGraphMusicPlaylist, J as QlaraOpenGraphMusicRadioStation, K as QlaraOpenGraphMusicSong, L as QlaraOpenGraphProfile, N as QlaraOpenGraphVideoEpisode, O as QlaraOpenGraphVideoMovie, S as QlaraOpenGraphVideoOther, T as QlaraOpenGraphVideoTVShow, U as QlaraOpenGraphWebsite, V as QlaraPinterest, Q as QlaraProvider, W as QlaraReferrer, X as QlaraRobots, Y as QlaraRobotsInfo, Z as QlaraRouteDefinition, _ as QlaraRoutes, $ as QlaraTwitter, a0 as QlaraTwitterApp, a1 as QlaraTwitterAppDescriptor, a2 as QlaraTwitterBase, a3 as QlaraTwitterImage, a4 as QlaraTwitterImageDescriptor, a5 as QlaraTwitterPlayer, a6 as QlaraTwitterPlayerDescriptor, a7 as QlaraTwitterSummary, a8 as QlaraTwitterSummaryLargeImage, a9 as QlaraValidate, aa as QlaraVerification } from './types-BmSR1R_Q.js';
 
 declare function validateConfig(config: QlaraPluginConfig, routes: QlaraRoute[]): void;
 

package/dist/plugin/next.d.cts

@@ -1,5 +1,5 @@
 import { NextConfig } from 'next';
-import { a as QlaraPluginConfig } from '../types--KPPgCtc.cjs';
+import { a as QlaraPluginConfig } from '../types-BmSR1R_Q.cjs';
 
 /**
  * Wrap a Next.js config with Qlara.

package/dist/plugin/next.d.ts

@@ -1,5 +1,5 @@
 import { NextConfig } from 'next';
-import { a as QlaraPluginConfig } from '../types--KPPgCtc.js';
+import { a as QlaraPluginConfig } from '../types-BmSR1R_Q.js';
 
 /**
  * Wrap a Next.js config with Qlara.

package/dist/{types--KPPgCtc.d.cts → types-BmSR1R_Q.d.cts}

@@ -315,31 +315,60 @@ interface QlaraMetadata {
     other?: Record<string, string | number | (string | number)[]>;
 }
 /**
- * Function that fetches data for a dynamic route and returns metadata.
+ * Function that generates metadata for a dynamic route.
  * Equivalent to Next.js `generateMetadata()` — runs in the renderer Lambda
  * with access to the data source.
  *
- * @param params - The route parameters, e.g. { id: '42' } for /product/:id
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' } for /:lang/products/:id
  * @returns Metadata for the page, or null if the page doesn't exist
  */
 type QlaraMetaDataGenerator = (params: Record<string, string>) => Promise<QlaraMetadata | null>;
-/** A single route definition with its pattern and metadata generator. */
+/**
+ * Optional validation function for a dynamic route.
+ * Called before reading the fallback or generating metadata.
+ * Use this to cheaply reject invalid param combinations (e.g., unsupported languages).
+ *
+ * Receives ALL route parameters — you can validate every dynamic segment.
+ *
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' }
+ * @returns true if the params are valid, false to return 404 immediately
+ */
+type QlaraValidate = (params: Record<string, string>) => Promise<boolean>;
+/**
+ * A single route definition at the leaf page level.
+ *
+ * Follows the Next.js "generate from bottom up" pattern:
+ * define one route entry per leaf page with ALL dynamic params.
+ */
 interface QlaraRouteDefinition {
-    /** Dynamic route pattern, e.g. '/product/:id' */
+    /** Dynamic route pattern, e.g. '/:lang/products/:id' */
     route: string;
-    /** Function that fetches metadata for this route from the data source */
-    metaDataGenerator: QlaraMetaDataGenerator;
+    /**
+     * Optional validation function — called before rendering.
+     * Return `false` to 404 immediately without generating the page.
+     * Receives all params so you can validate every dynamic segment.
+     */
+    validate?: QlaraValidate;
+    /**
+     * Function that generates metadata for this route.
+     * Preferred name — use this instead of `metaDataGenerator`.
+     */
+    generateMetadata?: QlaraMetaDataGenerator;
+    /**
+     * @deprecated Use `generateMetadata` instead. Kept for backward compatibility.
+     */
+    metaDataGenerator?: QlaraMetaDataGenerator;
 }
 /**
  * The route file default export type: an array of route definitions.
  *
- * Example:
+ * Example (single param):
  * ```typescript
  * import type { QlaraRoutes } from 'qlara';
  * const routes: QlaraRoutes = [
  *   {
  *     route: '/product/:id',
- *     metaDataGenerator: async (params) => {
+ *     generateMetadata: async (params) => {
  *       const product = await getProduct(params.id);
  *       if (!product) return null;
  *       return { title: product.name, description: product.description };
@@ -348,6 +377,25 @@ interface QlaraRouteDefinition {
  * ];
  * export default routes;
  * ```
+ *
+ * Example (multiple params with validation):
+ * ```typescript
+ * const routes: QlaraRoutes = [
+ *   {
+ *     route: '/:lang/products/:id',
+ *     validate: async (params) => {
+ *       if (!['en', 'da', 'de'].includes(params.lang)) return false;
+ *       const product = await getProduct(params.id);
+ *       return !!product;
+ *     },
+ *     generateMetadata: async (params) => {
+ *       const product = await getProduct(params.id);
+ *       if (!product) return null;
+ *       return { title: `${product.name} | Store` };
+ *     },
+ *   },
+ * ];
+ * ```
  */
 type QlaraRoutes = QlaraRouteDefinition[];
 interface QlaraRoute {
@@ -420,4 +468,4 @@ interface RouteMatch {
     params: Record<string, string>;
 }
 
-export type { QlaraTwitter as $, QlaraOGImageDescriptor as A, QlaraOGVideo as B, QlaraOGVideoDescriptor as C, QlaraOpenGraph as D, QlaraOpenGraphArticle as E, QlaraOpenGraphBase as F, QlaraOpenGraphBook as G, QlaraOpenGraphMusicAlbum as H, QlaraOpenGraphMusicPlaylist as I, QlaraOpenGraphMusicRadioStation as J, QlaraOpenGraphMusicSong as K, QlaraOpenGraphProfile as L, ManifestRoute as M, QlaraOpenGraphVideoEpisode as N, QlaraOpenGraphVideoMovie as O, ProviderResources as P, QlaraProvider as Q, RouteMatch as R, QlaraOpenGraphVideoOther as S, QlaraOpenGraphVideoTVShow as T, QlaraOpenGraphWebsite as U, QlaraPinterest as V, QlaraReferrer as W, QlaraRobots as X, QlaraRobotsInfo as Y, QlaraRouteDefinition as Z, QlaraRoutes as _, QlaraPluginConfig as a, QlaraTwitterApp as a0, QlaraTwitterAppDescriptor as a1, QlaraTwitterBase as a2, QlaraTwitterImage as a3, QlaraTwitterImageDescriptor as a4, QlaraTwitterPlayer as a5, QlaraTwitterPlayerDescriptor as a6, QlaraTwitterSummary as a7, QlaraTwitterSummaryLargeImage as a8, QlaraVerification as a9, QlaraRoute as b, QlaraManifest as c, QlaraAlternateLinkDescriptor as d, QlaraAlternateURLs as e, QlaraAppLinks as f, QlaraAppLinksAndroid as g, QlaraAppLinksApple as h, QlaraAppLinksWeb as i, QlaraAppLinksWindows as j, QlaraAppleImage as k, QlaraAppleImageDescriptor as l, QlaraAppleWebApp as m, QlaraAuthor as n, QlaraDeployConfig as o, QlaraFacebook as p, QlaraFormatDetection as q, QlaraIcon as r, QlaraIconDescriptor as s, QlaraIcons as t, QlaraItunesApp as u, QlaraMetaDataGenerator as v, QlaraMetadata as w, QlaraOGAudio as x, QlaraOGAudioDescriptor as y, QlaraOGImage as z };
+export type { QlaraTwitter as $, QlaraOGImageDescriptor as A, QlaraOGVideo as B, QlaraOGVideoDescriptor as C, QlaraOpenGraph as D, QlaraOpenGraphArticle as E, QlaraOpenGraphBase as F, QlaraOpenGraphBook as G, QlaraOpenGraphMusicAlbum as H, QlaraOpenGraphMusicPlaylist as I, QlaraOpenGraphMusicRadioStation as J, QlaraOpenGraphMusicSong as K, QlaraOpenGraphProfile as L, ManifestRoute as M, QlaraOpenGraphVideoEpisode as N, QlaraOpenGraphVideoMovie as O, ProviderResources as P, QlaraProvider as Q, RouteMatch as R, QlaraOpenGraphVideoOther as S, QlaraOpenGraphVideoTVShow as T, QlaraOpenGraphWebsite as U, QlaraPinterest as V, QlaraReferrer as W, QlaraRobots as X, QlaraRobotsInfo as Y, QlaraRouteDefinition as Z, QlaraRoutes as _, QlaraPluginConfig as a, QlaraTwitterApp as a0, QlaraTwitterAppDescriptor as a1, QlaraTwitterBase as a2, QlaraTwitterImage as a3, QlaraTwitterImageDescriptor as a4, QlaraTwitterPlayer as a5, QlaraTwitterPlayerDescriptor as a6, QlaraTwitterSummary as a7, QlaraTwitterSummaryLargeImage as a8, QlaraValidate as a9, QlaraVerification as aa, QlaraRoute as b, QlaraManifest as c, QlaraAlternateLinkDescriptor as d, QlaraAlternateURLs as e, QlaraAppLinks as f, QlaraAppLinksAndroid as g, QlaraAppLinksApple as h, QlaraAppLinksWeb as i, QlaraAppLinksWindows as j, QlaraAppleImage as k, QlaraAppleImageDescriptor as l, QlaraAppleWebApp as m, QlaraAuthor as n, QlaraDeployConfig as o, QlaraFacebook as p, QlaraFormatDetection as q, QlaraIcon as r, QlaraIconDescriptor as s, QlaraIcons as t, QlaraItunesApp as u, QlaraMetaDataGenerator as v, QlaraMetadata as w, QlaraOGAudio as x, QlaraOGAudioDescriptor as y, QlaraOGImage as z };

package/dist/{types--KPPgCtc.d.ts → types-BmSR1R_Q.d.ts}

@@ -315,31 +315,60 @@ interface QlaraMetadata {
     other?: Record<string, string | number | (string | number)[]>;
 }
 /**
- * Function that fetches data for a dynamic route and returns metadata.
+ * Function that generates metadata for a dynamic route.
  * Equivalent to Next.js `generateMetadata()` — runs in the renderer Lambda
  * with access to the data source.
  *
- * @param params - The route parameters, e.g. { id: '42' } for /product/:id
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' } for /:lang/products/:id
  * @returns Metadata for the page, or null if the page doesn't exist
  */
 type QlaraMetaDataGenerator = (params: Record<string, string>) => Promise<QlaraMetadata | null>;
-/** A single route definition with its pattern and metadata generator. */
+/**
+ * Optional validation function for a dynamic route.
+ * Called before reading the fallback or generating metadata.
+ * Use this to cheaply reject invalid param combinations (e.g., unsupported languages).
+ *
+ * Receives ALL route parameters — you can validate every dynamic segment.
+ *
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' }
+ * @returns true if the params are valid, false to return 404 immediately
+ */
+type QlaraValidate = (params: Record<string, string>) => Promise<boolean>;
+/**
+ * A single route definition at the leaf page level.
+ *
+ * Follows the Next.js "generate from bottom up" pattern:
+ * define one route entry per leaf page with ALL dynamic params.
+ */
 interface QlaraRouteDefinition {
-    /** Dynamic route pattern, e.g. '/product/:id' */
+    /** Dynamic route pattern, e.g. '/:lang/products/:id' */
     route: string;
-    /** Function that fetches metadata for this route from the data source */
-    metaDataGenerator: QlaraMetaDataGenerator;
+    /**
+     * Optional validation function — called before rendering.
+     * Return `false` to 404 immediately without generating the page.
+     * Receives all params so you can validate every dynamic segment.
+     */
+    validate?: QlaraValidate;
+    /**
+     * Function that generates metadata for this route.
+     * Preferred name — use this instead of `metaDataGenerator`.
+     */
+    generateMetadata?: QlaraMetaDataGenerator;
+    /**
+     * @deprecated Use `generateMetadata` instead. Kept for backward compatibility.
+     */
+    metaDataGenerator?: QlaraMetaDataGenerator;
 }
 /**
  * The route file default export type: an array of route definitions.
  *
- * Example:
+ * Example (single param):
  * ```typescript
  * import type { QlaraRoutes } from 'qlara';
  * const routes: QlaraRoutes = [
  *   {
  *     route: '/product/:id',
- *     metaDataGenerator: async (params) => {
+ *     generateMetadata: async (params) => {
  *       const product = await getProduct(params.id);
  *       if (!product) return null;
  *       return { title: product.name, description: product.description };
@@ -348,6 +377,25 @@ interface QlaraRouteDefinition {
  * ];
  * export default routes;
  * ```
+ *
+ * Example (multiple params with validation):
+ * ```typescript
+ * const routes: QlaraRoutes = [
+ *   {
+ *     route: '/:lang/products/:id',
+ *     validate: async (params) => {
+ *       if (!['en', 'da', 'de'].includes(params.lang)) return false;
+ *       const product = await getProduct(params.id);
+ *       return !!product;
+ *     },
+ *     generateMetadata: async (params) => {
+ *       const product = await getProduct(params.id);
+ *       if (!product) return null;
+ *       return { title: `${product.name} | Store` };
+ *     },
+ *   },
+ * ];
+ * ```
  */
 type QlaraRoutes = QlaraRouteDefinition[];
 interface QlaraRoute {
@@ -420,4 +468,4 @@ interface RouteMatch {
     params: Record<string, string>;
 }
 
-export type { QlaraTwitter as $, QlaraOGImageDescriptor as A, QlaraOGVideo as B, QlaraOGVideoDescriptor as C, QlaraOpenGraph as D, QlaraOpenGraphArticle as E, QlaraOpenGraphBase as F, QlaraOpenGraphBook as G, QlaraOpenGraphMusicAlbum as H, QlaraOpenGraphMusicPlaylist as I, QlaraOpenGraphMusicRadioStation as J, QlaraOpenGraphMusicSong as K, QlaraOpenGraphProfile as L, ManifestRoute as M, QlaraOpenGraphVideoEpisode as N, QlaraOpenGraphVideoMovie as O, ProviderResources as P, QlaraProvider as Q, RouteMatch as R, QlaraOpenGraphVideoOther as S, QlaraOpenGraphVideoTVShow as T, QlaraOpenGraphWebsite as U, QlaraPinterest as V, QlaraReferrer as W, QlaraRobots as X, QlaraRobotsInfo as Y, QlaraRouteDefinition as Z, QlaraRoutes as _, QlaraPluginConfig as a, QlaraTwitterApp as a0, QlaraTwitterAppDescriptor as a1, QlaraTwitterBase as a2, QlaraTwitterImage as a3, QlaraTwitterImageDescriptor as a4, QlaraTwitterPlayer as a5, QlaraTwitterPlayerDescriptor as a6, QlaraTwitterSummary as a7, QlaraTwitterSummaryLargeImage as a8, QlaraVerification as a9, QlaraRoute as b, QlaraManifest as c, QlaraAlternateLinkDescriptor as d, QlaraAlternateURLs as e, QlaraAppLinks as f, QlaraAppLinksAndroid as g, QlaraAppLinksApple as h, QlaraAppLinksWeb as i, QlaraAppLinksWindows as j, QlaraAppleImage as k, QlaraAppleImageDescriptor as l, QlaraAppleWebApp as m, QlaraAuthor as n, QlaraDeployConfig as o, QlaraFacebook as p, QlaraFormatDetection as q, QlaraIcon as r, QlaraIconDescriptor as s, QlaraIcons as t, QlaraItunesApp as u, QlaraMetaDataGenerator as v, QlaraMetadata as w, QlaraOGAudio as x, QlaraOGAudioDescriptor as y, QlaraOGImage as z };
+export type { QlaraTwitter as $, QlaraOGImageDescriptor as A, QlaraOGVideo as B, QlaraOGVideoDescriptor as C, QlaraOpenGraph as D, QlaraOpenGraphArticle as E, QlaraOpenGraphBase as F, QlaraOpenGraphBook as G, QlaraOpenGraphMusicAlbum as H, QlaraOpenGraphMusicPlaylist as I, QlaraOpenGraphMusicRadioStation as J, QlaraOpenGraphMusicSong as K, QlaraOpenGraphProfile as L, ManifestRoute as M, QlaraOpenGraphVideoEpisode as N, QlaraOpenGraphVideoMovie as O, ProviderResources as P, QlaraProvider as Q, RouteMatch as R, QlaraOpenGraphVideoOther as S, QlaraOpenGraphVideoTVShow as T, QlaraOpenGraphWebsite as U, QlaraPinterest as V, QlaraReferrer as W, QlaraRobots as X, QlaraRobotsInfo as Y, QlaraRouteDefinition as Z, QlaraRoutes as _, QlaraPluginConfig as a, QlaraTwitterApp as a0, QlaraTwitterAppDescriptor as a1, QlaraTwitterBase as a2, QlaraTwitterImage as a3, QlaraTwitterImageDescriptor as a4, QlaraTwitterPlayer as a5, QlaraTwitterPlayerDescriptor as a6, QlaraTwitterSummary as a7, QlaraTwitterSummaryLargeImage as a8, QlaraValidate as a9, QlaraVerification as aa, QlaraRoute as b, QlaraManifest as c, QlaraAlternateLinkDescriptor as d, QlaraAlternateURLs as e, QlaraAppLinks as f, QlaraAppLinksAndroid as g, QlaraAppLinksApple as h, QlaraAppLinksWeb as i, QlaraAppLinksWindows as j, QlaraAppleImage as k, QlaraAppleImageDescriptor as l, QlaraAppleWebApp as m, QlaraAuthor as n, QlaraDeployConfig as o, QlaraFacebook as p, QlaraFormatDetection as q, QlaraIcon as r, QlaraIconDescriptor as s, QlaraIcons as t, QlaraItunesApp as u, QlaraMetaDataGenerator as v, QlaraMetadata as w, QlaraOGAudio as x, QlaraOGAudioDescriptor as y, QlaraOGImage as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlara",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Runtime ISR for static React apps — dynamic routing and SEO metadata for statically exported Next.js apps on AWS",
   "license": "MIT",
   "keywords": [

package/src/provider/aws/renderer.ts

@@ -78,8 +78,6 @@ interface RendererResult {
   html?: string;
 }
 
-const FALLBACK_PLACEHOLDER = '__QLARA_FALLBACK__';
-
 // Module-scope S3 client — reused across warm invocations (avoids recreating TCP/TLS connections)
 const s3 = new S3Client({ region: process.env.AWS_REGION || 'us-east-1' });
 
@@ -95,23 +93,27 @@ function deriveS3Key(uri: string): string {
 }
 
 /**
- * Derive the fallback S3 key from a URI.
- * /product/42 → product/_fallback.html
+ * Derive the fallback S3 key from a route pattern.
+ * Filters out dynamic segments (starting with ':') and appends _fallback.html.
+ * Must match getFallbackKey() in fallback.ts.
+ *
+ * '/product/:id' → 'product/_fallback.html'
+ * '/:lang/products/:id' → 'products/_fallback.html'
+ * '/:a/:b/:c' → '_fallback.html'
  */
-function deriveFallbackKey(uri: string): string {
-  const cleanUri = uri.replace(/^\//, '').replace(/\/$/, '');
-  const parts = cleanUri.split('/');
-  if (parts.length < 2) return '_fallback.html';
-  return parts.slice(0, -1).join('/') + '/_fallback.html';
+function deriveFallbackKey(routePattern: string): string {
+  const parts = routePattern.replace(/^\//, '').split('/');
+  const dirParts = parts.filter(p => !p.startsWith(':'));
+  return [...dirParts, '_fallback.html'].join('/');
 }
 
 /**
- * Extract the last path segment (the dynamic param value) from a URI.
- * /product/42 → '42'
+ * Generate a per-param placeholder string.
+ * Must match paramPlaceholder() in fallback.ts (inlined because renderer
+ * is bundled as a standalone Lambda ZIP).
  */
-function extractParamValue(uri: string): string {
-  const cleanUri = uri.replace(/^\//, '').replace(/\/$/, '');
-  return cleanUri.split('/').pop() || '';
+function paramPlaceholder(paramName: string): string {
+  return `__QLARA_FALLBACK_${paramName}__`;
 }
 
 // ── Helpers: normalize single-or-array values ────────────────────
@@ -832,6 +834,58 @@ async function findReferenceSegmentDir(bucket: string, routePrefix: string): Pro
   return null;
 }
 
+/**
+ * Find a reference segment directory using the route pattern.
+ * For multi-param routes like /:lang/products/:id, the direct URI-based prefix
+ * (e.g., 'da/products') may not contain any build-time pages. This function
+ * walks the S3 key hierarchy following the route pattern: static segments
+ * descend directly, dynamic segments list subdirectories and try any of them.
+ */
+async function findReferenceSegmentDirByPattern(
+  bucket: string,
+  routePattern: string,
+): Promise<string | null> {
+  // Remove the last segment (the page-level param) to get the parent segments
+  const segments = routePattern.replace(/^\//, '').split('/');
+  const parentSegments = segments.slice(0, -1);
+
+  async function searchPrefix(prefix: string, segmentIndex: number): Promise<string | null> {
+    if (segmentIndex >= parentSegments.length) {
+      // We've traversed all parent segments — check for segment files here
+      return findReferenceSegmentDir(bucket, prefix.replace(/\/$/, ''));
+    }
+
+    const segment = parentSegments[segmentIndex];
+
+    if (!segment.startsWith(':')) {
+      // Static segment — descend directly
+      const nextPrefix = prefix ? `${prefix}${segment}/` : `${segment}/`;
+      return searchPrefix(nextPrefix, segmentIndex + 1);
+    }
+
+    // Dynamic segment — list subdirectories and try each
+    try {
+      const response = await s3.send(new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: prefix,
+        Delimiter: '/',
+        MaxKeys: 10,
+      }));
+
+      for (const commonPrefix of response.CommonPrefixes || []) {
+        const subPrefix = commonPrefix.Prefix || '';
+        const result = await searchPrefix(subPrefix, segmentIndex + 1);
+        if (result) return result;
+      }
+    } catch {
+      // S3 error — skip
+    }
+    return null;
+  }
+
+  return searchPrefix('', 0);
+}
+
 type SegmentFileType = 'shared' | 'tree' | 'head' | 'full' | 'page';
 
 /**
@@ -866,13 +920,19 @@ async function listReferenceSegmentFiles(bucket: string, refDir: string): Promis
 }
 
 /**
- * Patch the _tree.txt segment: replace the dynamic paramKey value.
+ * Patch the _tree.txt segment: replace dynamic paramKey values for all params.
+ * Each dynamic segment has "name":"<paramName>","paramType":"d","paramKey":"<value>".
+ * We match on the param name to replace the correct paramKey for each param.
  */
-function patchTreeSegment(template: string, newValue: string): string {
-  return template.replace(
-    /"paramType":"d","paramKey":"[^"]*"/,
-    `"paramType":"d","paramKey":"${newValue}"`
-  );
+function patchTreeSegment(template: string, params: Record<string, string>): string {
+  let result = template;
+  for (const [name, value] of Object.entries(params)) {
+    result = result.replace(
+      new RegExp(`"name":"${name}","paramType":"d","paramKey":"[^"]*"`),
+      `"name":"${name}","paramType":"d","paramKey":"${value}"`
+    );
+  }
+  return result;
 }
 
 /**
@@ -996,14 +1056,19 @@ async function generateSegmentFiles(
   params: Record<string, string>,
   rscData: string | null,
   metadata: QlaraMetadata | null,
+  routePattern: string,
 ): Promise<void> {
   const cleanUri = uri.replace(/^\//, '').replace(/\/$/, '');
   const parts = cleanUri.split('/');
-  const routePrefix = parts.slice(0, -1).join('/'); // 'product'
-  const segmentDir = `${cleanUri}/`;                 // 'product/42/'
-
-  // Find a build-time page with segment files to use as reference
-  const refDir = await findReferenceSegmentDir(bucket, routePrefix);
+  const routePrefix = parts.slice(0, -1).join('/'); // 'da/products'
+  const segmentDir = `${cleanUri}/`;                 // 'da/products/42/'
+
+  // Find a build-time page with segment files to use as reference.
+  // Try the direct URI prefix first; fall back to pattern-based search for multi-param routes.
+  let refDir = await findReferenceSegmentDir(bucket, routePrefix);
+  if (!refDir) {
+    refDir = await findReferenceSegmentDirByPattern(bucket, routePattern);
+  }
   if (!refDir) return; // No segment files on S3 — Next.js 15 or no build-time pages
 
   // List all segment files in the reference directory
@@ -1033,7 +1098,6 @@ async function generateSegmentFiles(
   }
 
   // Generate each segment file
-  const paramValue = parts[parts.length - 1]; // last path segment = dynamic param value
   const uploads: Promise<unknown>[] = [];
   const cacheControl = `public, max-age=0, s-maxage=${__QLARA_CACHE_TTL__}, stale-while-revalidate=60`;
 
@@ -1048,7 +1112,7 @@ async function generateSegmentFiles(
       case 'tree': {
         const template = refMap.get(name);
         if (template) {
-          content = patchTreeSegment(template, paramValue);
+          content = patchTreeSegment(template, params);
         }
         break;
       }
@@ -1108,9 +1172,22 @@ export async function handler(event: RendererEvent & { warmup?: boolean }): Prom
   const { uri, bucket, routePattern, params } = event;
 
   try {
-    // 0. Check if already rendered + read fallback in parallel
+    // 0. Find route definition and run validation (if defined)
+    const routeDef = routes?.find((r: { route: string }) => r.route === routePattern);
+
+    if (routeDef?.validate) {
+      const isValid = await routeDef.validate(params);
+      if (!isValid) {
+        return {
+          statusCode: 404,
+          body: JSON.stringify({ error: `Validation failed for ${uri}`, params }),
+        };
+      }
+    }
+
+    // 1. Check if already rendered + read fallback in parallel
     const s3Key = deriveS3Key(uri);
-    const fallbackKey = deriveFallbackKey(uri);
+    const fallbackKey = deriveFallbackKey(routePattern);
 
     const [existingResult, fallbackResult] = await Promise.allSettled([
       s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })),
@@ -1147,19 +1224,18 @@ export async function handler(event: RendererEvent & { warmup?: boolean }): Prom
       };
     }
 
-    // 2. Patch the fallback with the actual param value
-    const paramValue = extractParamValue(uri);
-    let html = fallbackHtml.replace(
-      new RegExp(FALLBACK_PLACEHOLDER, 'g'),
-      paramValue
-    );
+    // 2. Patch the fallback with actual param values (per-param placeholders)
+    let html = fallbackHtml;
+    for (const [name, value] of Object.entries(params)) {
+      html = html.replace(new RegExp(paramPlaceholder(name), 'g'), value);
+    }
 
-    // 3. Call the metaDataGenerator to fetch metadata from the data source
-    const routeDef = routes?.find((r: { route: string }) => r.route === routePattern);
+    // 3. Call generateMetadata (or deprecated metaDataGenerator) to fetch metadata
+    const metadataFn = routeDef?.generateMetadata || routeDef?.metaDataGenerator;
     let metadata: QlaraMetadata | null = null;
 
-    if (routeDef?.metaDataGenerator) {
-      metadata = await routeDef.metaDataGenerator(params);
+    if (metadataFn) {
+      metadata = await metadataFn(params);
       if (metadata) {
         // 4. Patch the HTML with real metadata
         html = patchMetadata(html, metadata);
@@ -1198,7 +1274,7 @@ export async function handler(event: RendererEvent & { warmup?: boolean }): Prom
       // 7. Generate per-segment prefetch files (Next.js 16+ Segment Cache)
       //    Reads templates from a build-time reference page, patches page-specific data.
       //    Skips automatically for Next.js 15 (no segment files on S3).
-      await generateSegmentFiles(bucket, uri, params, rscData, metadata);
+      await generateSegmentFiles(bucket, uri, params, rscData, metadata, routePattern);
     }
 
     return {

package/src/types.ts

@@ -456,33 +456,63 @@ export interface QlaraMetadata {
 }
 
 /**
- * Function that fetches data for a dynamic route and returns metadata.
+ * Function that generates metadata for a dynamic route.
  * Equivalent to Next.js `generateMetadata()` — runs in the renderer Lambda
  * with access to the data source.
  *
- * @param params - The route parameters, e.g. { id: '42' } for /product/:id
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' } for /:lang/products/:id
  * @returns Metadata for the page, or null if the page doesn't exist
  */
 export type QlaraMetaDataGenerator = (params: Record<string, string>) => Promise<QlaraMetadata | null>;
 
-/** A single route definition with its pattern and metadata generator. */
+/**
+ * Optional validation function for a dynamic route.
+ * Called before reading the fallback or generating metadata.
+ * Use this to cheaply reject invalid param combinations (e.g., unsupported languages).
+ *
+ * Receives ALL route parameters — you can validate every dynamic segment.
+ *
+ * @param params - All route parameters, e.g. { lang: 'en', id: '42' }
+ * @returns true if the params are valid, false to return 404 immediately
+ */
+export type QlaraValidate = (params: Record<string, string>) => Promise<boolean>;
+
+/**
+ * A single route definition at the leaf page level.
+ *
+ * Follows the Next.js "generate from bottom up" pattern:
+ * define one route entry per leaf page with ALL dynamic params.
+ */
 export interface QlaraRouteDefinition {
-  /** Dynamic route pattern, e.g. '/product/:id' */
+  /** Dynamic route pattern, e.g. '/:lang/products/:id' */
   route: string;
-  /** Function that fetches metadata for this route from the data source */
-  metaDataGenerator: QlaraMetaDataGenerator;
+  /**
+   * Optional validation function — called before rendering.
+   * Return `false` to 404 immediately without generating the page.
+   * Receives all params so you can validate every dynamic segment.
+   */
+  validate?: QlaraValidate;
+  /**
+   * Function that generates metadata for this route.
+   * Preferred name — use this instead of `metaDataGenerator`.
+   */
+  generateMetadata?: QlaraMetaDataGenerator;
+  /**
+   * @deprecated Use `generateMetadata` instead. Kept for backward compatibility.
+   */
+  metaDataGenerator?: QlaraMetaDataGenerator;
 }
 
 /**
  * The route file default export type: an array of route definitions.
  *
- * Example:
+ * Example (single param):
  * ```typescript
  * import type { QlaraRoutes } from 'qlara';
  * const routes: QlaraRoutes = [
  *   {
  *     route: '/product/:id',
- *     metaDataGenerator: async (params) => {
+ *     generateMetadata: async (params) => {
  *       const product = await getProduct(params.id);
  *       if (!product) return null;
  *       return { title: product.name, description: product.description };
@@ -491,6 +521,25 @@ export interface QlaraRouteDefinition {
  * ];
  * export default routes;
  * ```
+ *
+ * Example (multiple params with validation):
+ * ```typescript
+ * const routes: QlaraRoutes = [
+ *   {
+ *     route: '/:lang/products/:id',
+ *     validate: async (params) => {
+ *       if (!['en', 'da', 'de'].includes(params.lang)) return false;
+ *       const product = await getProduct(params.id);
+ *       return !!product;
+ *     },
+ *     generateMetadata: async (params) => {
+ *       const product = await getProduct(params.id);
+ *       if (!product) return null;
+ *       return { title: `${product.name} | Store` };
+ *     },
+ *   },
+ * ];
+ * ```
  */
 export type QlaraRoutes = QlaraRouteDefinition[];