qlara 0.1.9 → 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.9",
+  "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

@@ -15,7 +15,7 @@
  * route definitions, each with a pattern and a metaDataGenerator function.
  */
 
-import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
 import type {
   QlaraMetadata,
   QlaraOpenGraph,
@@ -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 ────────────────────
@@ -788,6 +790,322 @@ function extractRscFlightData(html: string): string | null {
   return chunks.join('');
 }
 
+// ── Per-segment prefetch file generation (Next.js 16+) ───────────
+//
+// Next.js 16 introduced per-segment prefetch files in a subdirectory
+// per page (e.g. product/1/__next._tree.txt). The renderer must generate
+// these for renderer-created pages so they match build-time pages.
+//
+// Approach: discover segment files from a build-time reference page on S3,
+// classify each file, and copy/patch as needed. If no reference page exists
+// (Next.js 15 or no build-time pages), segment generation is skipped.
+
+/** Cache reference segment directory per route prefix across warm invocations */
+const referencePageCache = new Map<string, string | null>();
+
+/**
+ * Find a build-time page's segment directory in S3 to use as a template.
+ * Returns the S3 key prefix (e.g. 'product/1/') or null.
+ */
+async function findReferenceSegmentDir(bucket: string, routePrefix: string): Promise<string | null> {
+  const cached = referencePageCache.get(routePrefix);
+  if (cached !== undefined) return cached;
+
+  try {
+    const response = await s3.send(new ListObjectsV2Command({
+      Bucket: bucket,
+      Prefix: `${routePrefix}/`,
+      MaxKeys: 200,
+    }));
+
+    for (const obj of response.Contents || []) {
+      const key = obj.Key || '';
+      if (key.endsWith('/__next._tree.txt')) {
+        const dir = key.slice(0, key.length - '__next._tree.txt'.length);
+        referencePageCache.set(routePrefix, dir);
+        return dir;
+      }
+    }
+  } catch {
+    // S3 error — skip segment generation
+  }
+
+  referencePageCache.set(routePrefix, null);
+  return null;
+}
+
+type SegmentFileType = 'shared' | 'tree' | 'head' | 'full' | 'page';
+
+/**
+ * Classify a segment file by its name.
+ */
+function classifySegmentFile(name: string): SegmentFileType {
+  if (name === '__next._tree.txt') return 'tree';
+  if (name === '__next._head.txt') return 'head';
+  if (name === '__next._full.txt') return 'full';
+  if (name.includes('__PAGE__')) return 'page';
+  return 'shared';
+}
+
+/**
+ * List all segment file names in a reference directory.
+ */
+async function listReferenceSegmentFiles(bucket: string, refDir: string): Promise<string[]> {
+  try {
+    const response = await s3.send(new ListObjectsV2Command({
+      Bucket: bucket,
+      Prefix: `${refDir}__next.`,
+      MaxKeys: 50,
+    }));
+
+    return (response.Contents || [])
+      .map(obj => obj.Key || '')
+      .filter(key => key.endsWith('.txt'))
+      .map(key => key.slice(refDir.length));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 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, 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;
+}
+
+/**
+ * Patch the __PAGE__.txt segment: replace param values in the component props.
+ */
+function patchPageSegment(template: string, params: Record<string, string>): string {
+  let result = template;
+  for (const [key, value] of Object.entries(params)) {
+    // RSC wire format: ["$","$L2",null,{"id":"OLD"}]
+    result = result.replace(
+      new RegExp(`"${key}":"[^"]*"`),
+      `"${key}":"${value}"`
+    );
+  }
+  return result;
+}
+
+/**
+ * Generate the _head.txt segment from a reference template and new metadata.
+ * Extracts preamble (module declarations) and buildId from the reference,
+ * rebuilds line 0 with new metadata.
+ */
+function generateHeadSegment(template: string, metadata: QlaraMetadata): string {
+  // Split into lines — preamble is everything before the line starting with '0:'
+  const lines = template.split('\n');
+  const preambleLines: string[] = [];
+  let line0 = '';
+
+  for (const line of lines) {
+    if (line.startsWith('0:')) {
+      line0 = line;
+    } else if (line.trim()) {
+      preambleLines.push(line);
+    }
+  }
+
+  // Extract buildId from reference
+  const buildIdMatch = line0.match(/"buildId":"([^"]+)"/);
+  const buildId = buildIdMatch ? buildIdMatch[1] : '';
+
+  // Extract the viewport/charset meta tags from the reference (preserve them)
+  // These are inside the rsc at children[1] (the $L2 viewport boundary)
+  // We keep the structure identical but replace the metadata children
+  const viewportMatch = line0.match(/"children":\[(\["\\?\$","meta"[^\]]*\](?:,\["\\?\$","meta"[^\]]*\])*)\]/);
+  const viewportTags = viewportMatch ? viewportMatch[1] : '["\$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]';
+
+  // Build metadata RSC children array (standard JSON, not HTML-escaped)
+  const metaChildren: string[] = [];
+  let idx = 0;
+
+  // Title
+  metaChildren.push(`["$","title","${idx++}",{"children":"${escapeJson(metadata.title)}"}]`);
+
+  // Description
+  if (metadata.description) {
+    metaChildren.push(`["$","meta","${idx++}",{"name":"description","content":"${escapeJson(metadata.description)}"}]`);
+  }
+
+  // Open Graph
+  if (metadata.openGraph) {
+    const og = metadata.openGraph;
+    if (og.title) metaChildren.push(`["$","meta","${idx++}",{"property":"og:title","content":"${escapeJson(og.title)}"}]`);
+    if (og.description) metaChildren.push(`["$","meta","${idx++}",{"property":"og:description","content":"${escapeJson(og.description)}"}]`);
+    if (og.url) metaChildren.push(`["$","meta","${idx++}",{"property":"og:url","content":"${escapeJson(og.url)}"}]`);
+    if (og.siteName) metaChildren.push(`["$","meta","${idx++}",{"property":"og:site_name","content":"${escapeJson(og.siteName)}"}]`);
+    if (og.type) metaChildren.push(`["$","meta","${idx++}",{"property":"og:type","content":"${escapeJson(og.type)}"}]`);
+    for (const img of toArray(og.images)) {
+      if (typeof img === 'string') {
+        metaChildren.push(`["$","meta","${idx++}",{"property":"og:image","content":"${escapeJson(img)}"}]`);
+      } else {
+        metaChildren.push(`["$","meta","${idx++}",{"property":"og:image","content":"${escapeJson(img.url)}"}]`);
+        if (img.alt) metaChildren.push(`["$","meta","${idx++}",{"property":"og:image:alt","content":"${escapeJson(img.alt)}"}]`);
+        if (img.width !== undefined) metaChildren.push(`["$","meta","${idx++}",{"property":"og:image:width","content":"${String(img.width)}"}]`);
+        if (img.height !== undefined) metaChildren.push(`["$","meta","${idx++}",{"property":"og:image:height","content":"${String(img.height)}"}]`);
+      }
+    }
+  }
+
+  // Twitter
+  if (metadata.twitter) {
+    const tw = metadata.twitter;
+    const card = ('card' in tw && tw.card) ? tw.card : 'summary';
+    metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:card","content":"${escapeJson(card)}"}]`);
+    if (tw.title) metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:title","content":"${escapeJson(tw.title)}"}]`);
+    if (tw.description) metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:description","content":"${escapeJson(tw.description)}"}]`);
+    for (const img of toArray(tw.images)) {
+      if (typeof img === 'string') {
+        metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:image","content":"${escapeJson(img)}"}]`);
+      } else {
+        metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:image","content":"${escapeJson(img.url)}"}]`);
+        if (img.alt) metaChildren.push(`["$","meta","${idx++}",{"name":"twitter:image:alt","content":"${escapeJson(img.alt)}"}]`);
+      }
+    }
+  }
+
+  // Reconstruct the _head.txt content by replacing the metadata children
+  // in the reference template's line 0 structure
+  const metaChildrenStr = metaChildren.join(',');
+
+  // The _head.txt line 0 structure (from analysis):
+  // 0:{"buildId":"...","rsc":["$","$1","h",{"children":[null,["$","$L2",null,{"children":[viewport tags]}],["$","div",null,{"hidden":true,"children":["$","$L3",null,{"children":["$","$4",null,{"name":"Next.Metadata","children":[METADATA HERE]}]}]}],null]}],"loading":null,"isPartial":false}
+  // Replace the "Next.Metadata" children array
+  const newLine0 = line0.replace(
+    /("name":"Next\.Metadata","children":\[)[\s\S]*?(\]\})/,
+    `$1${metaChildrenStr}$2`
+  );
+
+  return preambleLines.join('\n') + '\n' + newLine0 + '\n';
+}
+
+/**
+ * Generate per-segment prefetch files for a renderer-created page (Next.js 16+).
+ * Reads segment files from a build-time reference page, patches page-specific data,
+ * and uploads to the new page's subdirectory.
+ *
+ * Skips gracefully if no reference page exists (Next.js 15 or first deploy).
+ */
+async function generateSegmentFiles(
+  bucket: string,
+  uri: string,
+  params: Record<string, string>,
+  rscData: string | null,
+  metadata: QlaraMetadata | null,
+): 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);
+  if (!refDir) return; // No segment files on S3 — Next.js 15 or no build-time pages
+
+  // List all segment files in the reference directory
+  const fileNames = await listReferenceSegmentFiles(bucket, refDir);
+  if (fileNames.length === 0) return;
+
+  // Read all reference files we need (skip _full — we use rscData directly)
+  const filesToRead = fileNames.filter(name => classifySegmentFile(name) !== 'full');
+  const readResults = await Promise.allSettled(
+    filesToRead.map(async (name) => {
+      const result = await s3.send(new GetObjectCommand({
+        Bucket: bucket,
+        Key: `${refDir}${name}`,
+      }));
+      return {
+        name,
+        content: await result.Body?.transformToString('utf-8') || '',
+      };
+    })
+  );
+
+  const refMap = new Map<string, string>();
+  for (const result of readResults) {
+    if (result.status === 'fulfilled' && result.value.content) {
+      refMap.set(result.value.name, result.value.content);
+    }
+  }
+
+  // Generate each segment file
+  const uploads: Promise<unknown>[] = [];
+  const cacheControl = `public, max-age=0, s-maxage=${__QLARA_CACHE_TTL__}, stale-while-revalidate=60`;
+
+  for (const name of fileNames) {
+    let content: string | null = null;
+    const type = classifySegmentFile(name);
+
+    switch (type) {
+      case 'shared':
+        content = refMap.get(name) || null;
+        break;
+      case 'tree': {
+        const template = refMap.get(name);
+        if (template) {
+          content = patchTreeSegment(template, params);
+        }
+        break;
+      }
+      case 'head': {
+        const template = refMap.get(name);
+        if (template && metadata) {
+          content = generateHeadSegment(template, metadata);
+        }
+        break;
+      }
+      case 'full':
+        content = rscData;
+        break;
+      case 'page': {
+        const template = refMap.get(name);
+        if (template) {
+          content = patchPageSegment(template, params);
+        }
+        break;
+      }
+    }
+
+    if (content) {
+      uploads.push(
+        s3.send(new PutObjectCommand({
+          Bucket: bucket,
+          Key: `${segmentDir}${name}`,
+          Body: content,
+          ContentType: 'text/plain; charset=utf-8',
+          CacheControl: cacheControl,
+        }))
+      );
+    }
+  }
+
+  await Promise.all(uploads);
+}
+
+/**
+ * Escape a string for use inside a JSON string value.
+ */
+function escapeJson(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
 export async function handler(event: RendererEvent & { warmup?: boolean }): Promise<RendererResult> {
   // Warmup invocation — just initialize the runtime and return
   if (event.warmup) {
@@ -797,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 })),
@@ -836,18 +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) {
-      const metadata = await routeDef.metaDataGenerator(params);
+    if (metadataFn) {
+      metadata = await metadataFn(params);
       if (metadata) {
         // 4. Patch the HTML with real metadata
         html = patchMetadata(html, metadata);
@@ -866,9 +1197,8 @@ export async function handler(event: RendererEvent & { warmup?: boolean }): Prom
     );
 
     // 6. Framework-specific post-render uploads
-    //    Next.js: extract RSC flight data and upload as .txt for client-side navigation.
-    //    Next.js fetches .txt instead of .html when using <Link> / client-side nav.
-    //    Without this, client-side nav falls back to a full page reload (slow).
+    //    Next.js: extract RSC flight data, upload .txt for client-side navigation,
+    //    and generate per-segment prefetch files (Next.js 16+).
     if (__QLARA_FRAMEWORK__ === 'next') {
       const rscData = extractRscFlightData(html);
       if (rscData) {
@@ -883,6 +1213,11 @@ 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);
     }
 
     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[];