@richie-router/server 0.1.4 → 0.1.5

package/dist/cjs/index.cjs

@@ -39,10 +39,11 @@ var __export = (target, all) => {
 // packages/server/src/index.ts
 var exports_src = {};
 __export(exports_src, {
-  matchesSpaRequest: () => matchesSpaRequest,
+  matchesSpaPath: () => matchesSpaPath,
   handleSpaRequest: () => handleSpaRequest,
   handleRequest: () => handleRequest,
   handleHeadTagRequest: () => handleHeadTagRequest,
+  handleHeadRequest: () => handleHeadRequest,
   defineHeadTags: () => defineHeadTags
 });
 module.exports = __toCommonJS(exports_src);
@@ -56,7 +57,8 @@ function defineHeadTags(routeManifest, routerSchema, definitions) {
 }
 var HEAD_PLACEHOLDER = "<!--richie-router-head-->";
 var MANAGED_HEAD_ATTRIBUTE = "data-richie-router-head";
-var EMPTY_HEAD = { meta: [], links: [], styles: [], scripts: [] };
+var HEAD_RESPONSE_KIND_HEADER = "x-richie-router-head";
+var EMPTY_HEAD = [];
 function ensureLeadingSlash(value) {
   return value.startsWith("/") ? value : `/${value}`;
 }
@@ -92,10 +94,16 @@ function prependBasePathToPathname(pathname, basePath) {
 function routeHasRecord(value) {
   return typeof value === "object" && value !== null;
 }
-function createHeadSnapshotScript(href, head) {
-  const payload = JSON.stringify({ href, head }).replaceAll("</script>", "<\\/script>");
+function createHeadSnapshotScript(href, head, routeHeads) {
+  const payload = JSON.stringify({ href, head, routeHeads }).replaceAll("</script>", "<\\/script>");
   return `<script ${MANAGED_HEAD_ATTRIBUTE}="true">window.__RICHIE_ROUTER_HEAD__=${payload}</script>`;
 }
+function createRichieRouterHead(href, head, routeHeads) {
+  const headHtml = import_core.serializeHeadConfig(head, {
+    managedAttribute: MANAGED_HEAD_ATTRIBUTE
+  });
+  return `${headHtml}${createHeadSnapshotScript(href, head, routeHeads)}`;
+}
 async function renderTemplate(html, ctx, options) {
   const template = html.template;
   if (typeof template === "function") {
@@ -110,12 +118,13 @@ async function renderTemplate(html, ctx, options) {
   return template.replace(HEAD_PLACEHOLDER, ctx.richieRouterHead);
 }
 function jsonResponse(data, init) {
+  const headers = new Headers(init?.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json; charset=utf-8");
+  }
   return new Response(JSON.stringify(data), {
     ...init,
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      ...init?.headers ?? {}
-    }
+    headers
   });
 }
 function notFoundResult() {
@@ -125,16 +134,43 @@ function notFoundResult() {
   };
 }
 function htmlResponse(html, headers) {
+  const responseHeaders = new Headers(headers);
+  if (!responseHeaders.has("content-type")) {
+    responseHeaders.set("content-type", "text/html; charset=utf-8");
+  }
   return new Response(html, {
     status: 200,
-    headers: {
-      "content-type": "text/html; charset=utf-8",
-      ...headers ?? {}
-    }
+    headers: responseHeaders
+  });
+}
+function withResponseHeaders(response, headersToSet) {
+  const headers = new Headers(response.headers);
+  new Headers(headersToSet).forEach((value, key) => {
+    headers.set(key, value);
+  });
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
   });
 }
+function formatHeadCacheControl(staleTime) {
+  if (staleTime === undefined) {
+    return "private, no-store";
+  }
+  return `private, max-age=${Math.max(0, Math.floor(staleTime / 1000))}`;
+}
+function createHeadResponseHeaders(kind, staleTime, headers) {
+  const responseHeaders = new Headers(headers);
+  responseHeaders.set(HEAD_RESPONSE_KIND_HEADER, kind);
+  responseHeaders.set("cache-control", formatHeadCacheControl(staleTime));
+  return responseHeaders;
+}
 function resolveDocumentRequest(request, basePathOption) {
-  const url = new URL(request.url);
+  return resolveDocumentPath(request.url, basePathOption);
+}
+function resolveDocumentPath(path, basePathOption) {
+  const url = new URL(path, "http://richie-router.local");
   const basePath = normalizeBasePath(basePathOption);
   const strippedPathname = stripBasePathFromPathname(url.pathname, basePath);
   if (strippedPathname === null) {
@@ -206,8 +242,8 @@ function matchesSpaLocation(options, location) {
   }
   return resolveSpaRoutes(options.spaRoutesManifest).some((route) => import_core.matchPathname(route, location.pathname) !== null);
 }
-function matchesSpaRequest(request, options) {
-  const documentRequest = resolveDocumentRequest(request, options.basePath);
+function matchesSpaPath(path, options) {
+  const documentRequest = resolveDocumentPath(path, options.basePath);
   if (documentRequest === null) {
     return false;
   }
@@ -232,16 +268,108 @@ async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
 }
 async function resolveMatchedHead(request, headTags, matches) {
   const resolvedHeadByRoute = new Map;
+  const routeHeads = [];
+  let staleTime;
   for (const match of matches) {
     if (!match.route.serverHead) {
       continue;
     }
     const result = await executeHeadTag(request, headTags, match.route.fullPath, match.params, match.search);
     resolvedHeadByRoute.set(match.route.fullPath, result.head);
+    routeHeads.push({
+      routeId: match.route.fullPath,
+      head: result.head,
+      staleTime: result.staleTime
+    });
+    if (result.staleTime !== undefined) {
+      staleTime = staleTime === undefined ? result.staleTime : Math.min(staleTime, result.staleTime);
+    }
   }
-  return import_core.resolveHeadConfig(matches, resolvedHeadByRoute);
+  return {
+    head: import_core.resolveHeadConfig(matches, resolvedHeadByRoute),
+    routeHeads,
+    staleTime
+  };
 }
-async function handleHeadTagRequest(request, options) {
+function createDocumentHeadRequest(sourceRequest, href) {
+  const requestUrl = new URL(sourceRequest.url);
+  const targetUrl = new URL(href, requestUrl);
+  return new Request(targetUrl.toString(), {
+    method: "GET",
+    headers: sourceRequest.headers
+  });
+}
+async function handleDocumentHeadRequest(request, options, href) {
+  const documentRequest = createDocumentHeadRequest(request, href);
+  const resolvedDocumentRequest = resolveDocumentRequest(documentRequest, options.basePath);
+  if (resolvedDocumentRequest === null) {
+    return {
+      matched: true,
+      response: jsonResponse({ message: "Not Found" }, {
+        status: 404,
+        headers: createHeadResponseHeaders("document")
+      })
+    };
+  }
+  try {
+    const matches = buildMatches(options.headTags.routeManifest, resolvedDocumentRequest.location);
+    if (matches.length === 0) {
+      return {
+        matched: true,
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("document")
+        })
+      };
+    }
+    const { head, routeHeads, staleTime } = await resolveMatchedHead(documentRequest, options.headTags, matches);
+    return {
+      matched: true,
+      response: jsonResponse({
+        href: resolvedDocumentRequest.location.href,
+        head,
+        routeHeads,
+        staleTime,
+        richieRouterHead: createRichieRouterHead(resolvedDocumentRequest.location.href, head, routeHeads)
+      }, {
+        headers: createHeadResponseHeaders("document", staleTime)
+      })
+    };
+  } catch (error) {
+    if (import_core.isRedirect(error)) {
+      const redirectPath = prependBasePathToPathname(import_core.buildPath(error.options.to, error.options.params ?? {}), resolvedDocumentRequest.basePath);
+      const redirectSearch = import_core.defaultStringifySearch(error.options.search === true ? {} : error.options.search ?? {});
+      const redirectHash = error.options.hash ? `#${error.options.hash.replace(/^#/, "")}` : "";
+      const redirectUrl = `${redirectPath}${redirectSearch}${redirectHash}`;
+      return {
+        matched: true,
+        response: new Response(null, {
+          status: error.options.replace ? 307 : 302,
+          headers: createHeadResponseHeaders("document", undefined, {
+            location: redirectUrl
+          })
+        })
+      };
+    }
+    if (error instanceof Response) {
+      return {
+        matched: true,
+        response: withResponseHeaders(error, createHeadResponseHeaders("document"))
+      };
+    }
+    if (import_core.isNotFound(error)) {
+      return {
+        matched: true,
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("document")
+        })
+      };
+    }
+    throw error;
+  }
+}
+async function handleHeadRequest(request, options) {
   const url = new URL(request.url);
   const basePath = normalizeBasePath(options.basePath);
   const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
@@ -251,11 +379,21 @@ async function handleHeadTagRequest(request, options) {
       response: new Response("Not Found", { status: 404 })
     };
   }
+  const href = url.searchParams.get("href");
+  if (href !== null) {
+    return await handleDocumentHeadRequest(request, {
+      ...options,
+      basePath
+    }, href);
+  }
   const routeId = url.searchParams.get("routeId");
   if (!routeId) {
     return {
       matched: true,
-      response: jsonResponse({ message: "Missing routeId" }, { status: 400 })
+      response: jsonResponse({ message: "Missing routeId" }, {
+        status: 400,
+        headers: createHeadResponseHeaders("route")
+      })
     };
   }
   const params = JSON.parse(url.searchParams.get("params") ?? "{}");
@@ -264,24 +402,32 @@ async function handleHeadTagRequest(request, options) {
     const result = await executeHeadTag(request, options.headTags, routeId, params, search);
     return {
       matched: true,
-      response: jsonResponse(result)
+      response: jsonResponse(result, {
+        headers: createHeadResponseHeaders("route", result.staleTime)
+      })
     };
   } catch (error) {
     if (error instanceof Response) {
       return {
         matched: true,
-        response: error
+        response: withResponseHeaders(error, createHeadResponseHeaders("route"))
       };
     }
     if (import_core.isNotFound(error)) {
       return {
         matched: true,
-        response: jsonResponse({ message: "Not Found" }, { status: 404 })
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("route")
+        })
       };
     }
     throw error;
   }
 }
+async function handleHeadTagRequest(request, options) {
+  return await handleHeadRequest(request, options);
+}
 async function handleSpaRequest(request, options) {
   const documentRequest = resolveDocumentRequest(request, options.basePath);
   if (documentRequest === null) {
@@ -314,11 +460,8 @@ async function handleRequest(request, options) {
     return notFoundResult();
   }
   try {
-    const head = await resolveMatchedHead(request, options.headTags, matches);
-    const headHtml = import_core.serializeHeadConfig(head, {
-      managedAttribute: MANAGED_HEAD_ATTRIBUTE
-    });
-    const richieRouterHead = `${headHtml}${createHeadSnapshotScript(documentRequest.location.href, head)}`;
+    const { head, routeHeads } = await resolveMatchedHead(request, options.headTags, matches);
+    const richieRouterHead = createRichieRouterHead(documentRequest.location.href, head, routeHeads);
     return await renderDocumentResponse(request, options.html, richieRouterHead, head, {
       headers: options.headers
     });

package/dist/cjs/index.test.cjs

@@ -32,13 +32,20 @@ function createTestArtifacts(options) {
   });
   const headTags = import__.defineHeadTags(rootRoute, routerSchema, {
     "/about": {
+      staleTime: options?.aboutStaleTime,
       head: () => {
         if (options?.redirectAbout) {
           import_core.redirect({ to: "/" });
         }
-        return {
-          meta: [{ title: "About" }]
-        };
+        return [
+          { tag: "title", children: "About" },
+          ...options?.customHeadElement ? [{
+            tag: "link",
+            rel: "icon",
+            href: "/favicon.ico",
+            sizes: "any"
+          }] : []
+        ];
       }
     }
   });
@@ -63,15 +70,15 @@ function createTestArtifacts(options) {
 import_bun_test.describe("handleSpaRequest", () => {
   import_bun_test.test("exposes a pure SPA matcher for host-side routing decisions", () => {
     const { spaRoutesManifest, routeManifest } = createTestArtifacts();
-    import_bun_test.expect(import__.matchesSpaRequest(new Request("https://example.com/project/about"), {
+    import_bun_test.expect(import__.matchesSpaPath("/project/about", {
       spaRoutesManifest,
       basePath: "/project"
     })).toBe(true);
-    import_bun_test.expect(import__.matchesSpaRequest(new Request("https://example.com/project/posts/123"), {
+    import_bun_test.expect(import__.matchesSpaPath("/project/posts/123", {
       routeManifest,
       basePath: "/project"
     })).toBe(true);
-    import_bun_test.expect(import__.matchesSpaRequest(new Request("https://example.com/project/api/health"), {
+    import_bun_test.expect(import__.matchesSpaPath("/project/api/health", {
       spaRoutesManifest,
       basePath: "/project"
     })).toBe(false);
@@ -205,9 +212,9 @@ import_bun_test.describe("handleRequest basePath", () => {
     import_bun_test.expect(result.matched).toBe(true);
     import_bun_test.expect(result.response.status).toBe(200);
     import_bun_test.expect(await result.response.json()).toEqual({
-      head: {
-        meta: [{ title: "About" }]
-      }
+      head: [
+        { tag: "title", children: "About" }
+      ]
     });
   });
   import_bun_test.test("allows direct head tag handling with basePath shorthand", async () => {
@@ -219,10 +226,95 @@ import_bun_test.describe("handleRequest basePath", () => {
     import_bun_test.expect(result.matched).toBe(true);
     import_bun_test.expect(result.response.status).toBe(200);
     import_bun_test.expect(await result.response.json()).toEqual({
-      head: {
-        meta: [{ title: "About" }]
+      head: [
+        { tag: "title", children: "About" }
+      ]
+    });
+  });
+  import_bun_test.test("resolves merged document head payloads for host-rendered HTML shells", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(200);
+    const payload = await result.response.json();
+    import_bun_test.expect(payload.href).toBe("/about");
+    import_bun_test.expect(payload.head).toEqual([
+      { tag: "title", children: "About" }
+    ]);
+    import_bun_test.expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ]
       }
+    ]);
+    import_bun_test.expect(payload.richieRouterHead).toContain("About</title>");
+    import_bun_test.expect(payload.richieRouterHead).toContain("window.__RICHIE_ROUTER_HEAD__");
+    import_bun_test.expect(result.response.headers.get("cache-control")).toBe("private, no-store");
+  });
+  import_bun_test.test("returns redirect responses for document head payload requests", async () => {
+    const { headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(302);
+    import_bun_test.expect(result.response.headers.get("location")).toBe("/project");
+  });
+  import_bun_test.test("serializes custom head elements for rich host templates", async () => {
+    const { headTags } = createTestArtifacts({
+      customHeadElement: true
+    });
+    const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    const payload = await result.response.json();
+    import_bun_test.expect(payload.richieRouterHead).toContain('<link rel="icon" href="/favicon.ico" sizes="any" data-richie-router-head="true">');
+  });
+  import_bun_test.test("derives cache-control headers from route staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 60000
+    });
+    const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
     });
+    import_bun_test.expect(result.response.headers.get("cache-control")).toBe("private, max-age=60");
+    import_bun_test.expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ],
+      staleTime: 60000
+    });
+  });
+  import_bun_test.test("derives document cache-control headers from the matched staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 5000
+    });
+    const result = await import__.handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    import_bun_test.expect(result.response.headers.get("cache-control")).toBe("private, max-age=5");
+    const payload = await result.response.json();
+    import_bun_test.expect(payload.staleTime).toBe(5000);
+    import_bun_test.expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ],
+        staleTime: 5000
+      }
+    ]);
   });
   import_bun_test.test("preserves custom headers on successful document responses", async () => {
     const { routeManifest, headTags } = createTestArtifacts();

package/dist/esm/index.mjs

@@ -20,7 +20,8 @@ function defineHeadTags(routeManifest, routerSchema, definitions) {
 }
 var HEAD_PLACEHOLDER = "<!--richie-router-head-->";
 var MANAGED_HEAD_ATTRIBUTE = "data-richie-router-head";
-var EMPTY_HEAD = { meta: [], links: [], styles: [], scripts: [] };
+var HEAD_RESPONSE_KIND_HEADER = "x-richie-router-head";
+var EMPTY_HEAD = [];
 function ensureLeadingSlash(value) {
   return value.startsWith("/") ? value : `/${value}`;
 }
@@ -56,10 +57,16 @@ function prependBasePathToPathname(pathname, basePath) {
 function routeHasRecord(value) {
   return typeof value === "object" && value !== null;
 }
-function createHeadSnapshotScript(href, head) {
-  const payload = JSON.stringify({ href, head }).replaceAll("</script>", "<\\/script>");
+function createHeadSnapshotScript(href, head, routeHeads) {
+  const payload = JSON.stringify({ href, head, routeHeads }).replaceAll("</script>", "<\\/script>");
   return `<script ${MANAGED_HEAD_ATTRIBUTE}="true">window.__RICHIE_ROUTER_HEAD__=${payload}</script>`;
 }
+function createRichieRouterHead(href, head, routeHeads) {
+  const headHtml = serializeHeadConfig(head, {
+    managedAttribute: MANAGED_HEAD_ATTRIBUTE
+  });
+  return `${headHtml}${createHeadSnapshotScript(href, head, routeHeads)}`;
+}
 async function renderTemplate(html, ctx, options) {
   const template = html.template;
   if (typeof template === "function") {
@@ -74,12 +81,13 @@ async function renderTemplate(html, ctx, options) {
   return template.replace(HEAD_PLACEHOLDER, ctx.richieRouterHead);
 }
 function jsonResponse(data, init) {
+  const headers = new Headers(init?.headers);
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json; charset=utf-8");
+  }
   return new Response(JSON.stringify(data), {
     ...init,
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      ...init?.headers ?? {}
-    }
+    headers
   });
 }
 function notFoundResult() {
@@ -89,16 +97,43 @@ function notFoundResult() {
   };
 }
 function htmlResponse(html, headers) {
+  const responseHeaders = new Headers(headers);
+  if (!responseHeaders.has("content-type")) {
+    responseHeaders.set("content-type", "text/html; charset=utf-8");
+  }
   return new Response(html, {
     status: 200,
-    headers: {
-      "content-type": "text/html; charset=utf-8",
-      ...headers ?? {}
-    }
+    headers: responseHeaders
+  });
+}
+function withResponseHeaders(response, headersToSet) {
+  const headers = new Headers(response.headers);
+  new Headers(headersToSet).forEach((value, key) => {
+    headers.set(key, value);
+  });
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
   });
 }
+function formatHeadCacheControl(staleTime) {
+  if (staleTime === undefined) {
+    return "private, no-store";
+  }
+  return `private, max-age=${Math.max(0, Math.floor(staleTime / 1000))}`;
+}
+function createHeadResponseHeaders(kind, staleTime, headers) {
+  const responseHeaders = new Headers(headers);
+  responseHeaders.set(HEAD_RESPONSE_KIND_HEADER, kind);
+  responseHeaders.set("cache-control", formatHeadCacheControl(staleTime));
+  return responseHeaders;
+}
 function resolveDocumentRequest(request, basePathOption) {
-  const url = new URL(request.url);
+  return resolveDocumentPath(request.url, basePathOption);
+}
+function resolveDocumentPath(path, basePathOption) {
+  const url = new URL(path, "http://richie-router.local");
   const basePath = normalizeBasePath(basePathOption);
   const strippedPathname = stripBasePathFromPathname(url.pathname, basePath);
   if (strippedPathname === null) {
@@ -170,8 +205,8 @@ function matchesSpaLocation(options, location) {
   }
   return resolveSpaRoutes(options.spaRoutesManifest).some((route) => matchPathname(route, location.pathname) !== null);
 }
-function matchesSpaRequest(request, options) {
-  const documentRequest = resolveDocumentRequest(request, options.basePath);
+function matchesSpaPath(path, options) {
+  const documentRequest = resolveDocumentPath(path, options.basePath);
   if (documentRequest === null) {
     return false;
   }
@@ -196,16 +231,108 @@ async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
 }
 async function resolveMatchedHead(request, headTags, matches) {
   const resolvedHeadByRoute = new Map;
+  const routeHeads = [];
+  let staleTime;
   for (const match of matches) {
     if (!match.route.serverHead) {
       continue;
     }
     const result = await executeHeadTag(request, headTags, match.route.fullPath, match.params, match.search);
     resolvedHeadByRoute.set(match.route.fullPath, result.head);
+    routeHeads.push({
+      routeId: match.route.fullPath,
+      head: result.head,
+      staleTime: result.staleTime
+    });
+    if (result.staleTime !== undefined) {
+      staleTime = staleTime === undefined ? result.staleTime : Math.min(staleTime, result.staleTime);
+    }
   }
-  return resolveHeadConfig(matches, resolvedHeadByRoute);
+  return {
+    head: resolveHeadConfig(matches, resolvedHeadByRoute),
+    routeHeads,
+    staleTime
+  };
 }
-async function handleHeadTagRequest(request, options) {
+function createDocumentHeadRequest(sourceRequest, href) {
+  const requestUrl = new URL(sourceRequest.url);
+  const targetUrl = new URL(href, requestUrl);
+  return new Request(targetUrl.toString(), {
+    method: "GET",
+    headers: sourceRequest.headers
+  });
+}
+async function handleDocumentHeadRequest(request, options, href) {
+  const documentRequest = createDocumentHeadRequest(request, href);
+  const resolvedDocumentRequest = resolveDocumentRequest(documentRequest, options.basePath);
+  if (resolvedDocumentRequest === null) {
+    return {
+      matched: true,
+      response: jsonResponse({ message: "Not Found" }, {
+        status: 404,
+        headers: createHeadResponseHeaders("document")
+      })
+    };
+  }
+  try {
+    const matches = buildMatches(options.headTags.routeManifest, resolvedDocumentRequest.location);
+    if (matches.length === 0) {
+      return {
+        matched: true,
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("document")
+        })
+      };
+    }
+    const { head, routeHeads, staleTime } = await resolveMatchedHead(documentRequest, options.headTags, matches);
+    return {
+      matched: true,
+      response: jsonResponse({
+        href: resolvedDocumentRequest.location.href,
+        head,
+        routeHeads,
+        staleTime,
+        richieRouterHead: createRichieRouterHead(resolvedDocumentRequest.location.href, head, routeHeads)
+      }, {
+        headers: createHeadResponseHeaders("document", staleTime)
+      })
+    };
+  } catch (error) {
+    if (isRedirect(error)) {
+      const redirectPath = prependBasePathToPathname(buildPath(error.options.to, error.options.params ?? {}), resolvedDocumentRequest.basePath);
+      const redirectSearch = defaultStringifySearch(error.options.search === true ? {} : error.options.search ?? {});
+      const redirectHash = error.options.hash ? `#${error.options.hash.replace(/^#/, "")}` : "";
+      const redirectUrl = `${redirectPath}${redirectSearch}${redirectHash}`;
+      return {
+        matched: true,
+        response: new Response(null, {
+          status: error.options.replace ? 307 : 302,
+          headers: createHeadResponseHeaders("document", undefined, {
+            location: redirectUrl
+          })
+        })
+      };
+    }
+    if (error instanceof Response) {
+      return {
+        matched: true,
+        response: withResponseHeaders(error, createHeadResponseHeaders("document"))
+      };
+    }
+    if (isNotFound(error)) {
+      return {
+        matched: true,
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("document")
+        })
+      };
+    }
+    throw error;
+  }
+}
+async function handleHeadRequest(request, options) {
   const url = new URL(request.url);
   const basePath = normalizeBasePath(options.basePath);
   const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
@@ -215,11 +342,21 @@ async function handleHeadTagRequest(request, options) {
       response: new Response("Not Found", { status: 404 })
     };
   }
+  const href = url.searchParams.get("href");
+  if (href !== null) {
+    return await handleDocumentHeadRequest(request, {
+      ...options,
+      basePath
+    }, href);
+  }
   const routeId = url.searchParams.get("routeId");
   if (!routeId) {
     return {
       matched: true,
-      response: jsonResponse({ message: "Missing routeId" }, { status: 400 })
+      response: jsonResponse({ message: "Missing routeId" }, {
+        status: 400,
+        headers: createHeadResponseHeaders("route")
+      })
     };
   }
   const params = JSON.parse(url.searchParams.get("params") ?? "{}");
@@ -228,24 +365,32 @@ async function handleHeadTagRequest(request, options) {
     const result = await executeHeadTag(request, options.headTags, routeId, params, search);
     return {
       matched: true,
-      response: jsonResponse(result)
+      response: jsonResponse(result, {
+        headers: createHeadResponseHeaders("route", result.staleTime)
+      })
     };
   } catch (error) {
     if (error instanceof Response) {
       return {
         matched: true,
-        response: error
+        response: withResponseHeaders(error, createHeadResponseHeaders("route"))
       };
     }
     if (isNotFound(error)) {
       return {
         matched: true,
-        response: jsonResponse({ message: "Not Found" }, { status: 404 })
+        response: jsonResponse({ message: "Not Found" }, {
+          status: 404,
+          headers: createHeadResponseHeaders("route")
+        })
       };
     }
     throw error;
   }
 }
+async function handleHeadTagRequest(request, options) {
+  return await handleHeadRequest(request, options);
+}
 async function handleSpaRequest(request, options) {
   const documentRequest = resolveDocumentRequest(request, options.basePath);
   if (documentRequest === null) {
@@ -278,11 +423,8 @@ async function handleRequest(request, options) {
     return notFoundResult();
   }
   try {
-    const head = await resolveMatchedHead(request, options.headTags, matches);
-    const headHtml = serializeHeadConfig(head, {
-      managedAttribute: MANAGED_HEAD_ATTRIBUTE
-    });
-    const richieRouterHead = `${headHtml}${createHeadSnapshotScript(documentRequest.location.href, head)}`;
+    const { head, routeHeads } = await resolveMatchedHead(request, options.headTags, matches);
+    const richieRouterHead = createRichieRouterHead(documentRequest.location.href, head, routeHeads);
     return await renderDocumentResponse(request, options.html, richieRouterHead, head, {
       headers: options.headers
     });
@@ -318,9 +460,10 @@ async function handleRequest(request, options) {
   }
 }
 export {
-  matchesSpaRequest,
+  matchesSpaPath,
   handleSpaRequest,
   handleRequest,
   handleHeadTagRequest,
+  handleHeadRequest,
   defineHeadTags
 };

package/dist/esm/index.test.mjs

@@ -1,7 +1,7 @@
 // packages/server/src/index.test.ts
 import { describe, expect, test } from "bun:test";
 import { defineRouterSchema, redirect, createRouteNode } from "@richie-router/core";
-import { defineHeadTags, handleHeadTagRequest, handleRequest, handleSpaRequest, matchesSpaRequest } from "./index.mjs";
+import { defineHeadTags, handleHeadRequest, handleHeadTagRequest, handleRequest, handleSpaRequest, matchesSpaPath } from "./index.mjs";
 function createTestArtifacts(options) {
   const rootRoute = createRouteNode("__root__", {}, { isRoot: true });
   const indexRoute = createRouteNode("/", {});
@@ -32,13 +32,20 @@ function createTestArtifacts(options) {
   });
   const headTags = defineHeadTags(rootRoute, routerSchema, {
     "/about": {
+      staleTime: options?.aboutStaleTime,
       head: () => {
         if (options?.redirectAbout) {
           redirect({ to: "/" });
         }
-        return {
-          meta: [{ title: "About" }]
-        };
+        return [
+          { tag: "title", children: "About" },
+          ...options?.customHeadElement ? [{
+            tag: "link",
+            rel: "icon",
+            href: "/favicon.ico",
+            sizes: "any"
+          }] : []
+        ];
       }
     }
   });
@@ -63,15 +70,15 @@ function createTestArtifacts(options) {
 describe("handleSpaRequest", () => {
   test("exposes a pure SPA matcher for host-side routing decisions", () => {
     const { spaRoutesManifest, routeManifest } = createTestArtifacts();
-    expect(matchesSpaRequest(new Request("https://example.com/project/about"), {
+    expect(matchesSpaPath("/project/about", {
       spaRoutesManifest,
       basePath: "/project"
     })).toBe(true);
-    expect(matchesSpaRequest(new Request("https://example.com/project/posts/123"), {
+    expect(matchesSpaPath("/project/posts/123", {
       routeManifest,
       basePath: "/project"
     })).toBe(true);
-    expect(matchesSpaRequest(new Request("https://example.com/project/api/health"), {
+    expect(matchesSpaPath("/project/api/health", {
       spaRoutesManifest,
       basePath: "/project"
     })).toBe(false);
@@ -205,9 +212,9 @@ describe("handleRequest basePath", () => {
     expect(result.matched).toBe(true);
     expect(result.response.status).toBe(200);
     expect(await result.response.json()).toEqual({
-      head: {
-        meta: [{ title: "About" }]
-      }
+      head: [
+        { tag: "title", children: "About" }
+      ]
     });
   });
   test("allows direct head tag handling with basePath shorthand", async () => {
@@ -219,10 +226,95 @@ describe("handleRequest basePath", () => {
     expect(result.matched).toBe(true);
     expect(result.response.status).toBe(200);
     expect(await result.response.json()).toEqual({
-      head: {
-        meta: [{ title: "About" }]
+      head: [
+        { tag: "title", children: "About" }
+      ]
+    });
+  });
+  test("resolves merged document head payloads for host-rendered HTML shells", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const payload = await result.response.json();
+    expect(payload.href).toBe("/about");
+    expect(payload.head).toEqual([
+      { tag: "title", children: "About" }
+    ]);
+    expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ]
       }
+    ]);
+    expect(payload.richieRouterHead).toContain("About</title>");
+    expect(payload.richieRouterHead).toContain("window.__RICHIE_ROUTER_HEAD__");
+    expect(result.response.headers.get("cache-control")).toBe("private, no-store");
+  });
+  test("returns redirect responses for document head payload requests", async () => {
+    const { headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(302);
+    expect(result.response.headers.get("location")).toBe("/project");
+  });
+  test("serializes custom head elements for rich host templates", async () => {
+    const { headTags } = createTestArtifacts({
+      customHeadElement: true
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    const payload = await result.response.json();
+    expect(payload.richieRouterHead).toContain('<link rel="icon" href="/favicon.ico" sizes="any" data-richie-router-head="true">');
+  });
+  test("derives cache-control headers from route staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 60000
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
     });
+    expect(result.response.headers.get("cache-control")).toBe("private, max-age=60");
+    expect(await result.response.json()).toEqual({
+      head: [
+        { tag: "title", children: "About" }
+      ],
+      staleTime: 60000
+    });
+  });
+  test("derives document cache-control headers from the matched staleTime", async () => {
+    const { headTags } = createTestArtifacts({
+      aboutStaleTime: 5000
+    });
+    const result = await handleHeadRequest(new Request("https://example.com/project/head-api?href=%2Fproject%2Fabout"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.response.headers.get("cache-control")).toBe("private, max-age=5");
+    const payload = await result.response.json();
+    expect(payload.staleTime).toBe(5000);
+    expect(payload.routeHeads).toEqual([
+      {
+        routeId: "/about",
+        head: [
+          { tag: "title", children: "About" }
+        ],
+        staleTime: 5000
+      }
+    ]);
   });
   test("preserves custom headers on successful document responses", async () => {
     const { routeManifest, headTags } = createTestArtifacts();

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type RouterSchemaShape, type InferRouterSearchSchema, type AnyRoute, type HeadConfig } from '@richie-router/core';
+import { type ResolveAllParamsForRouteId, type RouteIdsWithServerHead, type RouterSchemaShape, type InferRouterSearchSchema, type AnyRoute, type HeadConfig, type RouteHeadEntry } from '@richie-router/core';
 export interface HeadTagContext<TParams extends Record<string, string>, TSearch> {
     request: Request;
     params: TParams;
@@ -34,19 +34,19 @@ export interface SpaRoutesManifest {
     routes?: SpaRoutesManifestRoute[];
     spaRoutes: string[];
 }
-interface BaseMatchSpaRequestOptions {
+interface BaseMatchSpaPathOptions {
     basePath?: string;
 }
-export type MatchSpaRequestOptions = ({
+export type MatchSpaPathOptions = ({
     routeManifest: AnyRoute;
-} & BaseMatchSpaRequestOptions) | ({
+} & BaseMatchSpaPathOptions) | ({
     spaRoutesManifest: SpaRoutesManifest;
-} & BaseMatchSpaRequestOptions);
+} & BaseMatchSpaPathOptions);
 interface DocumentResponseOptions {
     html: HtmlOptions;
     headers?: HeadersInit;
 }
-export type HandleSpaRequestOptions = MatchSpaRequestOptions & DocumentResponseOptions;
+export type HandleSpaRequestOptions = MatchSpaPathOptions & DocumentResponseOptions;
 export interface HandleRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
     routeManifest: TRouteManifest;
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
@@ -64,7 +64,17 @@ export interface HandleRequestResult {
     matched: boolean;
     response: Response;
 }
-export declare function matchesSpaRequest(request: Request, options: MatchSpaRequestOptions): boolean;
+export interface RouteHeadResponsePayload {
+    head: HeadConfig;
+    staleTime?: number;
+}
+export interface DocumentHeadResponsePayload extends RouteHeadResponsePayload {
+    href: string;
+    richieRouterHead: string;
+    routeHeads: RouteHeadEntry[];
+}
+export declare function matchesSpaPath(path: string, options: MatchSpaPathOptions): boolean;
+export declare function handleHeadRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleHeadTagRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
 export declare function handleHeadTagRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleHeadTagRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;
 export declare function handleSpaRequest(request: Request, options: HandleSpaRequestOptions): Promise<HandleRequestResult>;
 export declare function handleRequest<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape>(request: Request, options: HandleRequestOptions<TRouteManifest, TRouterSchema>): Promise<HandleRequestResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richie-router/server",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Server helpers for Richie Router head tags and document handling",
   "sideEffects": false,
   "exports": {
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@richie-router/core": "^0.1.2"
+    "@richie-router/core": "^0.1.3"
   },
   "author": "Richie <oss@ricsam.dev>",
   "homepage": "https://docs.ricsam.dev/richie-router",