@richie-router/server 0.1.3 → 0.1.4

package/dist/cjs/index.cjs

@@ -39,6 +39,8 @@ var __export = (target, all) => {
 // packages/server/src/index.ts
 var exports_src = {};
 __export(exports_src, {
+  matchesSpaRequest: () => matchesSpaRequest,
+  handleSpaRequest: () => handleSpaRequest,
   handleRequest: () => handleRequest,
   handleHeadTagRequest: () => handleHeadTagRequest,
   defineHeadTags: () => defineHeadTags
@@ -54,6 +56,39 @@ 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: [] };
+function ensureLeadingSlash(value) {
+  return value.startsWith("/") ? value : `/${value}`;
+}
+function normalizeBasePath(basePath) {
+  if (!basePath) {
+    return "";
+  }
+  const trimmed = basePath.trim();
+  if (trimmed === "" || trimmed === "/") {
+    return "";
+  }
+  const normalized = ensureLeadingSlash(trimmed).replace(/\/+$/u, "");
+  return normalized === "/" ? "" : normalized;
+}
+function stripBasePathFromPathname(pathname, basePath) {
+  if (!basePath) {
+    return pathname;
+  }
+  if (pathname === basePath) {
+    return "/";
+  }
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || "/";
+  }
+  return null;
+}
+function prependBasePathToPathname(pathname, basePath) {
+  if (!basePath) {
+    return pathname;
+  }
+  return pathname === "/" ? basePath : `${basePath}${ensureLeadingSlash(pathname)}`;
+}
 function routeHasRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -61,12 +96,15 @@ function createHeadSnapshotScript(href, head) {
   const payload = JSON.stringify({ href, head }).replaceAll("</script>", "<\\/script>");
   return `<script ${MANAGED_HEAD_ATTRIBUTE}="true">window.__RICHIE_ROUTER_HEAD__=${payload}</script>`;
 }
-async function renderTemplate(html, ctx) {
+async function renderTemplate(html, ctx, options) {
   const template = html.template;
   if (typeof template === "function") {
     return await template(ctx);
   }
   if (!template.includes(HEAD_PLACEHOLDER)) {
+    if (options?.requireHeadPlaceholder === false) {
+      return template;
+    }
     throw new Error(`HTML template is missing required Richie Router placeholder: ${HEAD_PLACEHOLDER}`);
   }
   return template.replace(HEAD_PLACEHOLDER, ctx.richieRouterHead);
@@ -80,6 +118,46 @@ function jsonResponse(data, init) {
     }
   });
 }
+function notFoundResult() {
+  return {
+    matched: false,
+    response: new Response("Not Found", { status: 404 })
+  };
+}
+function htmlResponse(html, headers) {
+  return new Response(html, {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      ...headers ?? {}
+    }
+  });
+}
+function resolveDocumentRequest(request, basePathOption) {
+  const url = new URL(request.url);
+  const basePath = normalizeBasePath(basePathOption);
+  const strippedPathname = stripBasePathFromPathname(url.pathname, basePath);
+  if (strippedPathname === null) {
+    return null;
+  }
+  return {
+    basePath,
+    location: import_core.createParsedLocation(`${strippedPathname}${url.search}${url.hash}`, null, import_core.defaultParseSearch)
+  };
+}
+async function renderDocumentResponse(request, html, richieRouterHead, head, options) {
+  const template = await renderTemplate(html, {
+    request,
+    richieRouterHead,
+    head
+  }, {
+    requireHeadPlaceholder: options?.requireHeadPlaceholder
+  });
+  return {
+    matched: true,
+    response: htmlResponse(template, options?.headers)
+  };
+}
 function resolveSearch(route, rawSearch) {
   const fromSchema = route.searchSchema ? route.searchSchema.parse(rawSearch) : {};
   if (routeHasRecord(fromSchema)) {
@@ -112,6 +190,29 @@ function buildMatches(routeManifest, location) {
     };
   });
 }
+function resolveSpaRoutes(spaRoutesManifest) {
+  if (!routeHasRecord(spaRoutesManifest)) {
+    throw new Error("Invalid spaRoutesManifest: expected an object.");
+  }
+  const { spaRoutes } = spaRoutesManifest;
+  if (!Array.isArray(spaRoutes) || spaRoutes.some((route) => typeof route !== "string")) {
+    throw new Error('Invalid spaRoutesManifest: expected "spaRoutes" to be an array of strings.');
+  }
+  return spaRoutes;
+}
+function matchesSpaLocation(options, location) {
+  if ("routeManifest" in options) {
+    return buildMatches(options.routeManifest, location).length > 0;
+  }
+  return resolveSpaRoutes(options.spaRoutesManifest).some((route) => import_core.matchPathname(route, location.pathname) !== null);
+}
+function matchesSpaRequest(request, options) {
+  const documentRequest = resolveDocumentRequest(request, options.basePath);
+  if (documentRequest === null) {
+    return false;
+  }
+  return matchesSpaLocation(options, documentRequest.location);
+}
 async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
   const definition = headTags.definitions[routeId];
   const schemaEntry = headTags.routerSchema[routeId];
@@ -142,7 +243,8 @@ async function resolveMatchedHead(request, headTags, matches) {
 }
 async function handleHeadTagRequest(request, options) {
   const url = new URL(request.url);
-  const headBasePath = options.headBasePath ?? "/head-api";
+  const basePath = normalizeBasePath(options.basePath);
+  const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
   if (url.pathname !== headBasePath) {
     return {
       matched: false,
@@ -180,53 +282,49 @@ async function handleHeadTagRequest(request, options) {
     throw error;
   }
 }
+async function handleSpaRequest(request, options) {
+  const documentRequest = resolveDocumentRequest(request, options.basePath);
+  if (documentRequest === null) {
+    return notFoundResult();
+  }
+  if (!matchesSpaLocation(options, documentRequest.location)) {
+    return notFoundResult();
+  }
+  return await renderDocumentResponse(request, options.html, "", EMPTY_HEAD, {
+    headers: options.headers,
+    requireHeadPlaceholder: false
+  });
+}
 async function handleRequest(request, options) {
-  const url = new URL(request.url);
-  const routeBasePath = options.routeBasePath ?? "/";
+  const basePath = normalizeBasePath(options.basePath);
   const handledHeadTagRequest = await handleHeadTagRequest(request, {
     headTags: options.headTags,
+    basePath,
     headBasePath: options.headBasePath
   });
   if (handledHeadTagRequest.matched) {
     return handledHeadTagRequest;
   }
-  if (!url.pathname.startsWith(routeBasePath)) {
-    return {
-      matched: false,
-      response: new Response("Not Found", { status: 404 })
-    };
+  const documentRequest = resolveDocumentRequest(request, basePath);
+  if (documentRequest === null) {
+    return notFoundResult();
   }
-  const location = import_core.createParsedLocation(`${url.pathname}${url.search}${url.hash}`, null, import_core.defaultParseSearch);
-  const matches = buildMatches(options.routeManifest, location);
+  const matches = buildMatches(options.routeManifest, documentRequest.location);
   if (matches.length === 0) {
-    return {
-      matched: false,
-      response: new Response("Not Found", { status: 404 })
-    };
+    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(location.href, head)}`;
-    const html = await renderTemplate(options.html, {
-      request,
-      richieRouterHead,
-      head
+    const richieRouterHead = `${headHtml}${createHeadSnapshotScript(documentRequest.location.href, head)}`;
+    return await renderDocumentResponse(request, options.html, richieRouterHead, head, {
+      headers: options.headers
     });
-    return {
-      matched: true,
-      response: new Response(html, {
-        status: 200,
-        headers: {
-          "content-type": "text/html; charset=utf-8"
-        }
-      })
-    };
   } catch (error) {
     if (import_core.isRedirect(error)) {
-      const redirectPath = import_core.buildPath(error.options.to, error.options.params ?? {});
+      const redirectPath = prependBasePathToPathname(import_core.buildPath(error.options.to, error.options.params ?? {}), documentRequest.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}`;

package/dist/cjs/index.test.cjs

@@ -0,0 +1,243 @@
+// packages/server/src/index.test.ts
+var import_bun_test = require("bun:test");
+var import_core = require("@richie-router/core");
+var import__ = require("./index.cjs");
+function createTestArtifacts(options) {
+  const rootRoute = import_core.createRouteNode("__root__", {}, { isRoot: true });
+  const indexRoute = import_core.createRouteNode("/", {});
+  const authRoute = import_core.createRouteNode("/_auth", {});
+  const authDashboardRoute = import_core.createRouteNode("/_auth/dashboard", {});
+  const aboutRoute = import_core.createRouteNode("/about", {});
+  const postsRoute = import_core.createRouteNode("/posts", {});
+  const postsIndexRoute = import_core.createRouteNode("/posts/", {});
+  const postsPostIdRoute = import_core.createRouteNode("/posts/$postId", {});
+  aboutRoute._setServerHead(true);
+  authRoute._addFileChildren({
+    dashboard: authDashboardRoute
+  });
+  postsRoute._addFileChildren({
+    index: postsIndexRoute,
+    postId: postsPostIdRoute
+  });
+  rootRoute._addFileChildren({
+    index: indexRoute,
+    auth: authRoute,
+    about: aboutRoute,
+    posts: postsRoute
+  });
+  const routerSchema = import_core.defineRouterSchema({
+    "/about": {
+      serverHead: true
+    }
+  });
+  const headTags = import__.defineHeadTags(rootRoute, routerSchema, {
+    "/about": {
+      head: () => {
+        if (options?.redirectAbout) {
+          import_core.redirect({ to: "/" });
+        }
+        return {
+          meta: [{ title: "About" }]
+        };
+      }
+    }
+  });
+  return {
+    routeManifest: rootRoute,
+    headTags,
+    spaRoutesManifest: {
+      routes: [
+        { id: "__root__", to: "/", parentId: null, isRoot: true },
+        { id: "/", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth/dashboard", to: "/dashboard", parentId: "/_auth", isRoot: false },
+        { id: "/about", to: "/about", parentId: "__root__", isRoot: false },
+        { id: "/posts", to: "/posts", parentId: "__root__", isRoot: false },
+        { id: "/posts/", to: "/posts", parentId: "/posts", isRoot: false },
+        { id: "/posts/$postId", to: "/posts/$postId", parentId: "/posts", isRoot: false }
+      ],
+      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"]
+    }
+  };
+}
+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"), {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(true);
+    import_bun_test.expect(import__.matchesSpaRequest(new Request("https://example.com/project/posts/123"), {
+      routeManifest,
+      basePath: "/project"
+    })).toBe(true);
+    import_bun_test.expect(import__.matchesSpaRequest(new Request("https://example.com/project/api/health"), {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(false);
+  });
+  import_bun_test.test("matches document requests under the basePath with a routeManifest", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await import__.handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    import_bun_test.expect(html).not.toContain("window.__RICHIE_ROUTER_HEAD__");
+    import_bun_test.expect(html).toContain('<div id="app"></div>');
+    import_bun_test.expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+  import_bun_test.test("matches document requests under the basePath with a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await import__.handleSpaRequest(new Request("https://example.com/project/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(200);
+  });
+  import_bun_test.test("does not match sibling paths that only share the same prefix", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await import__.handleSpaRequest(new Request("https://example.com/projectish/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(false);
+    import_bun_test.expect(result.response.status).toBe(404);
+  });
+  import_bun_test.test("matches dynamic and pathless-derived public routes from a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    for (const pathname of ["/project/dashboard", "/project/posts/123"]) {
+      const result = await import__.handleSpaRequest(new Request(`https://example.com${pathname}`), {
+        spaRoutesManifest,
+        basePath: "/project",
+        html: {
+          template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+        }
+      });
+      import_bun_test.expect(result.matched).toBe(true);
+      import_bun_test.expect(result.response.status).toBe(200);
+    }
+  });
+  import_bun_test.test("allows string templates without the head placeholder", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await import__.handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head></head><body><div id="app"></div></body></html>'
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(await result.response.text()).toContain('<div id="app"></div>');
+  });
+});
+import_bun_test.describe("handleRequest basePath", () => {
+  import_bun_test.test("matches document requests under the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await import__.handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    import_bun_test.expect(html).toContain("About</title>");
+    import_bun_test.expect(html).toContain('<div id="app"></div>');
+  });
+  import_bun_test.test("does not match sibling paths that only share the same prefix", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await import__.handleRequest(new Request("https://example.com/projectish/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(false);
+    import_bun_test.expect(result.response.status).toBe(404);
+  });
+  import_bun_test.test("prefixes redirects with the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await import__.handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    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("uses the basePath for default head API requests handled through handleRequest", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await import__.handleRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    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" }]
+      }
+    });
+  });
+  import_bun_test.test("allows direct head tag handling with basePath shorthand", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await import__.handleHeadTagRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
+    });
+    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" }]
+      }
+    });
+  });
+  import_bun_test.test("preserves custom headers on successful document responses", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await import__.handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    import_bun_test.expect(result.matched).toBe(true);
+    import_bun_test.expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+});

package/dist/esm/index.mjs

@@ -6,6 +6,7 @@ import {
   defaultStringifySearch,
   isNotFound,
   isRedirect,
+  matchPathname,
   matchRouteTree,
   resolveHeadConfig,
   serializeHeadConfig
@@ -19,6 +20,39 @@ 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: [] };
+function ensureLeadingSlash(value) {
+  return value.startsWith("/") ? value : `/${value}`;
+}
+function normalizeBasePath(basePath) {
+  if (!basePath) {
+    return "";
+  }
+  const trimmed = basePath.trim();
+  if (trimmed === "" || trimmed === "/") {
+    return "";
+  }
+  const normalized = ensureLeadingSlash(trimmed).replace(/\/+$/u, "");
+  return normalized === "/" ? "" : normalized;
+}
+function stripBasePathFromPathname(pathname, basePath) {
+  if (!basePath) {
+    return pathname;
+  }
+  if (pathname === basePath) {
+    return "/";
+  }
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || "/";
+  }
+  return null;
+}
+function prependBasePathToPathname(pathname, basePath) {
+  if (!basePath) {
+    return pathname;
+  }
+  return pathname === "/" ? basePath : `${basePath}${ensureLeadingSlash(pathname)}`;
+}
 function routeHasRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -26,12 +60,15 @@ function createHeadSnapshotScript(href, head) {
   const payload = JSON.stringify({ href, head }).replaceAll("</script>", "<\\/script>");
   return `<script ${MANAGED_HEAD_ATTRIBUTE}="true">window.__RICHIE_ROUTER_HEAD__=${payload}</script>`;
 }
-async function renderTemplate(html, ctx) {
+async function renderTemplate(html, ctx, options) {
   const template = html.template;
   if (typeof template === "function") {
     return await template(ctx);
   }
   if (!template.includes(HEAD_PLACEHOLDER)) {
+    if (options?.requireHeadPlaceholder === false) {
+      return template;
+    }
     throw new Error(`HTML template is missing required Richie Router placeholder: ${HEAD_PLACEHOLDER}`);
   }
   return template.replace(HEAD_PLACEHOLDER, ctx.richieRouterHead);
@@ -45,6 +82,46 @@ function jsonResponse(data, init) {
     }
   });
 }
+function notFoundResult() {
+  return {
+    matched: false,
+    response: new Response("Not Found", { status: 404 })
+  };
+}
+function htmlResponse(html, headers) {
+  return new Response(html, {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      ...headers ?? {}
+    }
+  });
+}
+function resolveDocumentRequest(request, basePathOption) {
+  const url = new URL(request.url);
+  const basePath = normalizeBasePath(basePathOption);
+  const strippedPathname = stripBasePathFromPathname(url.pathname, basePath);
+  if (strippedPathname === null) {
+    return null;
+  }
+  return {
+    basePath,
+    location: createParsedLocation(`${strippedPathname}${url.search}${url.hash}`, null, defaultParseSearch)
+  };
+}
+async function renderDocumentResponse(request, html, richieRouterHead, head, options) {
+  const template = await renderTemplate(html, {
+    request,
+    richieRouterHead,
+    head
+  }, {
+    requireHeadPlaceholder: options?.requireHeadPlaceholder
+  });
+  return {
+    matched: true,
+    response: htmlResponse(template, options?.headers)
+  };
+}
 function resolveSearch(route, rawSearch) {
   const fromSchema = route.searchSchema ? route.searchSchema.parse(rawSearch) : {};
   if (routeHasRecord(fromSchema)) {
@@ -77,6 +154,29 @@ function buildMatches(routeManifest, location) {
     };
   });
 }
+function resolveSpaRoutes(spaRoutesManifest) {
+  if (!routeHasRecord(spaRoutesManifest)) {
+    throw new Error("Invalid spaRoutesManifest: expected an object.");
+  }
+  const { spaRoutes } = spaRoutesManifest;
+  if (!Array.isArray(spaRoutes) || spaRoutes.some((route) => typeof route !== "string")) {
+    throw new Error('Invalid spaRoutesManifest: expected "spaRoutes" to be an array of strings.');
+  }
+  return spaRoutes;
+}
+function matchesSpaLocation(options, location) {
+  if ("routeManifest" in options) {
+    return buildMatches(options.routeManifest, location).length > 0;
+  }
+  return resolveSpaRoutes(options.spaRoutesManifest).some((route) => matchPathname(route, location.pathname) !== null);
+}
+function matchesSpaRequest(request, options) {
+  const documentRequest = resolveDocumentRequest(request, options.basePath);
+  if (documentRequest === null) {
+    return false;
+  }
+  return matchesSpaLocation(options, documentRequest.location);
+}
 async function executeHeadTag(request, headTags, routeId, params, rawSearch) {
   const definition = headTags.definitions[routeId];
   const schemaEntry = headTags.routerSchema[routeId];
@@ -107,7 +207,8 @@ async function resolveMatchedHead(request, headTags, matches) {
 }
 async function handleHeadTagRequest(request, options) {
   const url = new URL(request.url);
-  const headBasePath = options.headBasePath ?? "/head-api";
+  const basePath = normalizeBasePath(options.basePath);
+  const headBasePath = options.headBasePath ?? prependBasePathToPathname("/head-api", basePath);
   if (url.pathname !== headBasePath) {
     return {
       matched: false,
@@ -145,53 +246,49 @@ async function handleHeadTagRequest(request, options) {
     throw error;
   }
 }
+async function handleSpaRequest(request, options) {
+  const documentRequest = resolveDocumentRequest(request, options.basePath);
+  if (documentRequest === null) {
+    return notFoundResult();
+  }
+  if (!matchesSpaLocation(options, documentRequest.location)) {
+    return notFoundResult();
+  }
+  return await renderDocumentResponse(request, options.html, "", EMPTY_HEAD, {
+    headers: options.headers,
+    requireHeadPlaceholder: false
+  });
+}
 async function handleRequest(request, options) {
-  const url = new URL(request.url);
-  const routeBasePath = options.routeBasePath ?? "/";
+  const basePath = normalizeBasePath(options.basePath);
   const handledHeadTagRequest = await handleHeadTagRequest(request, {
     headTags: options.headTags,
+    basePath,
     headBasePath: options.headBasePath
   });
   if (handledHeadTagRequest.matched) {
     return handledHeadTagRequest;
   }
-  if (!url.pathname.startsWith(routeBasePath)) {
-    return {
-      matched: false,
-      response: new Response("Not Found", { status: 404 })
-    };
+  const documentRequest = resolveDocumentRequest(request, basePath);
+  if (documentRequest === null) {
+    return notFoundResult();
   }
-  const location = createParsedLocation(`${url.pathname}${url.search}${url.hash}`, null, defaultParseSearch);
-  const matches = buildMatches(options.routeManifest, location);
+  const matches = buildMatches(options.routeManifest, documentRequest.location);
   if (matches.length === 0) {
-    return {
-      matched: false,
-      response: new Response("Not Found", { status: 404 })
-    };
+    return notFoundResult();
   }
   try {
     const head = await resolveMatchedHead(request, options.headTags, matches);
     const headHtml = serializeHeadConfig(head, {
       managedAttribute: MANAGED_HEAD_ATTRIBUTE
     });
-    const richieRouterHead = `${headHtml}${createHeadSnapshotScript(location.href, head)}`;
-    const html = await renderTemplate(options.html, {
-      request,
-      richieRouterHead,
-      head
+    const richieRouterHead = `${headHtml}${createHeadSnapshotScript(documentRequest.location.href, head)}`;
+    return await renderDocumentResponse(request, options.html, richieRouterHead, head, {
+      headers: options.headers
     });
-    return {
-      matched: true,
-      response: new Response(html, {
-        status: 200,
-        headers: {
-          "content-type": "text/html; charset=utf-8"
-        }
-      })
-    };
   } catch (error) {
     if (isRedirect(error)) {
-      const redirectPath = buildPath(error.options.to, error.options.params ?? {});
+      const redirectPath = prependBasePathToPathname(buildPath(error.options.to, error.options.params ?? {}), documentRequest.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}`;
@@ -221,6 +318,8 @@ async function handleRequest(request, options) {
   }
 }
 export {
+  matchesSpaRequest,
+  handleSpaRequest,
   handleRequest,
   handleHeadTagRequest,
   defineHeadTags

package/dist/esm/index.test.mjs

@@ -0,0 +1,243 @@
+// 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";
+function createTestArtifacts(options) {
+  const rootRoute = createRouteNode("__root__", {}, { isRoot: true });
+  const indexRoute = createRouteNode("/", {});
+  const authRoute = createRouteNode("/_auth", {});
+  const authDashboardRoute = createRouteNode("/_auth/dashboard", {});
+  const aboutRoute = createRouteNode("/about", {});
+  const postsRoute = createRouteNode("/posts", {});
+  const postsIndexRoute = createRouteNode("/posts/", {});
+  const postsPostIdRoute = createRouteNode("/posts/$postId", {});
+  aboutRoute._setServerHead(true);
+  authRoute._addFileChildren({
+    dashboard: authDashboardRoute
+  });
+  postsRoute._addFileChildren({
+    index: postsIndexRoute,
+    postId: postsPostIdRoute
+  });
+  rootRoute._addFileChildren({
+    index: indexRoute,
+    auth: authRoute,
+    about: aboutRoute,
+    posts: postsRoute
+  });
+  const routerSchema = defineRouterSchema({
+    "/about": {
+      serverHead: true
+    }
+  });
+  const headTags = defineHeadTags(rootRoute, routerSchema, {
+    "/about": {
+      head: () => {
+        if (options?.redirectAbout) {
+          redirect({ to: "/" });
+        }
+        return {
+          meta: [{ title: "About" }]
+        };
+      }
+    }
+  });
+  return {
+    routeManifest: rootRoute,
+    headTags,
+    spaRoutesManifest: {
+      routes: [
+        { id: "__root__", to: "/", parentId: null, isRoot: true },
+        { id: "/", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth", to: "/", parentId: "__root__", isRoot: false },
+        { id: "/_auth/dashboard", to: "/dashboard", parentId: "/_auth", isRoot: false },
+        { id: "/about", to: "/about", parentId: "__root__", isRoot: false },
+        { id: "/posts", to: "/posts", parentId: "__root__", isRoot: false },
+        { id: "/posts/", to: "/posts", parentId: "/posts", isRoot: false },
+        { id: "/posts/$postId", to: "/posts/$postId", parentId: "/posts", isRoot: false }
+      ],
+      spaRoutes: ["/", "/about", "/dashboard", "/posts", "/posts/$postId"]
+    }
+  };
+}
+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"), {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesSpaRequest(new Request("https://example.com/project/posts/123"), {
+      routeManifest,
+      basePath: "/project"
+    })).toBe(true);
+    expect(matchesSpaRequest(new Request("https://example.com/project/api/health"), {
+      spaRoutesManifest,
+      basePath: "/project"
+    })).toBe(false);
+  });
+  test("matches document requests under the basePath with a routeManifest", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    expect(html).not.toContain("window.__RICHIE_ROUTER_HEAD__");
+    expect(html).toContain('<div id="app"></div>');
+    expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+  test("matches document requests under the basePath with a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+  });
+  test("does not match sibling paths that only share the same prefix", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/projectish/about"), {
+      spaRoutesManifest,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(false);
+    expect(result.response.status).toBe(404);
+  });
+  test("matches dynamic and pathless-derived public routes from a spaRoutesManifest", async () => {
+    const { spaRoutesManifest } = createTestArtifacts();
+    for (const pathname of ["/project/dashboard", "/project/posts/123"]) {
+      const result = await handleSpaRequest(new Request(`https://example.com${pathname}`), {
+        spaRoutesManifest,
+        basePath: "/project",
+        html: {
+          template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+        }
+      });
+      expect(result.matched).toBe(true);
+      expect(result.response.status).toBe(200);
+    }
+  });
+  test("allows string templates without the head placeholder", async () => {
+    const { routeManifest } = createTestArtifacts();
+    const result = await handleSpaRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      basePath: "/project",
+      html: {
+        template: '<html><head></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(await result.response.text()).toContain('<div id="app"></div>');
+  });
+});
+describe("handleRequest basePath", () => {
+  test("matches document requests under the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    const html = await result.response.text();
+    expect(html).toContain("About</title>");
+    expect(html).toContain('<div id="app"></div>');
+  });
+  test("does not match sibling paths that only share the same prefix", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/projectish/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(false);
+    expect(result.response.status).toBe(404);
+  });
+  test("prefixes redirects with the basePath", async () => {
+    const { routeManifest, headTags } = createTestArtifacts({
+      redirectAbout: true
+    });
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(302);
+    expect(result.response.headers.get("location")).toBe("/project");
+  });
+  test("uses the basePath for default head API requests handled through handleRequest", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      html: {
+        template: "<html><head><!--richie-router-head--></head><body></body></html>"
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    expect(await result.response.json()).toEqual({
+      head: {
+        meta: [{ title: "About" }]
+      }
+    });
+  });
+  test("allows direct head tag handling with basePath shorthand", async () => {
+    const { headTags } = createTestArtifacts();
+    const result = await handleHeadTagRequest(new Request("https://example.com/project/head-api?routeId=%2Fabout&params=%7B%7D&search=%7B%7D"), {
+      headTags,
+      basePath: "/project"
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.status).toBe(200);
+    expect(await result.response.json()).toEqual({
+      head: {
+        meta: [{ title: "About" }]
+      }
+    });
+  });
+  test("preserves custom headers on successful document responses", async () => {
+    const { routeManifest, headTags } = createTestArtifacts();
+    const result = await handleRequest(new Request("https://example.com/project/about"), {
+      routeManifest,
+      headTags,
+      basePath: "/project",
+      headers: {
+        "cache-control": "no-cache"
+      },
+      html: {
+        template: '<html><head><!--richie-router-head--></head><body><div id="app"></div></body></html>'
+      }
+    });
+    expect(result.matched).toBe(true);
+    expect(result.response.headers.get("cache-control")).toBe("no-cache");
+  });
+});

package/dist/types/index.d.ts

@@ -24,20 +24,48 @@ export interface HtmlOptions {
         head: HeadConfig;
     }) => string | Promise<string>);
 }
+export interface SpaRoutesManifestRoute {
+    id: string;
+    to: string;
+    parentId: string | null;
+    isRoot: boolean;
+}
+export interface SpaRoutesManifest {
+    routes?: SpaRoutesManifestRoute[];
+    spaRoutes: string[];
+}
+interface BaseMatchSpaRequestOptions {
+    basePath?: string;
+}
+export type MatchSpaRequestOptions = ({
+    routeManifest: AnyRoute;
+} & BaseMatchSpaRequestOptions) | ({
+    spaRoutesManifest: SpaRoutesManifest;
+} & BaseMatchSpaRequestOptions);
+interface DocumentResponseOptions {
+    html: HtmlOptions;
+    headers?: HeadersInit;
+}
+export type HandleSpaRequestOptions = MatchSpaRequestOptions & DocumentResponseOptions;
 export interface HandleRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
     routeManifest: TRouteManifest;
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
     html: HtmlOptions;
+    basePath?: string;
+    headers?: HeadersInit;
     headBasePath?: string;
-    routeBasePath?: string;
 }
 export interface HandleHeadTagRequestOptions<TRouteManifest extends AnyRoute, TRouterSchema extends RouterSchemaShape> {
     headTags: DefinedHeadTags<TRouteManifest, TRouterSchema>;
+    basePath?: string;
     headBasePath?: string;
 }
 export interface HandleRequestResult {
     matched: boolean;
     response: Response;
 }
+export declare function matchesSpaRequest(request: Request, options: MatchSpaRequestOptions): boolean;
 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>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richie-router/server",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Server helpers for Richie Router head tags and document handling",
   "sideEffects": false,
   "exports": {