qlara 0.1.10 → 0.1.11

package/dist/aws.cjs

@@ -599,7 +599,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 +624,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -632,20 +634,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\\?"\}/,

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

@@ -595,7 +595,9 @@ var STACK_NAME_PREFIX = "qlara";
 import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2 } 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 +620,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -628,20 +630,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\\?"\}/,

package/dist/cli.js

@@ -603,7 +603,9 @@ async function bundleRenderer(routeFile, cacheTtl = 3600, framework) {
 import { readFileSync as readFileSync3, writeFileSync, readdirSync as readdirSync2, existsSync as existsSync2 } 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 +628,7 @@ function generateFallbackFromTemplate(templateHtml, routePattern) {
     );
     fallback = fallback.replace(
       propsRegex,
-      `{\\"${param}\\":\\"${FALLBACK_PLACEHOLDER}\\"}`
+      `{\\"${param}\\":\\"${paramPlaceholder(param)}\\"}`
     );
   }
   for (const param of paramNames) {
@@ -636,20 +638,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\\?"\}/,

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.11",
   "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 ────────────────────
@@ -866,13 +868,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;
 }
 
 /**
@@ -1033,7 +1041,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 +1055,7 @@ async function generateSegmentFiles(
       case 'tree': {
         const template = refMap.get(name);
         if (template) {
-          content = patchTreeSegment(template, paramValue);
+          content = patchTreeSegment(template, params);
         }
         break;
       }
@@ -1108,9 +1115,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 +1167,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);

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[];