@pracht/adapter-static 0.0.0 → 0.1.1

package/README.md

@@ -37,15 +37,32 @@ A static export has no server, so the build fails closed on anything that needs
 - API routes are build errors.
 - Manifest-registered capabilities exposed over HTTP/MCP/WebMCP are build errors (server-only capabilities invoked from build-time loaders are fine). Registered capability modules must load successfully so validation can fail closed; unused files in the capabilities directory are ignored.
 - Route patterns and concrete paths returned by `getStaticPaths()` may not write under the reserved `/_pracht/` namespace. Concrete output is preflighted before any page is written.
-- A Vite `base` other than `/` is a build error: prerendered documents reference `/assets/…` and `/_pracht/state/…` from the origin root, so a sub-path deploy (GitHub Pages project site, S3 key prefix) would build cleanly and serve a site whose every asset 404s.
+- A Vite `base` that is not a root-absolute path is a build error. CDN bases (`https://cdn.example.com/`, or protocol-relative `//cdn…`) relocate only assets while documents and `/_pracht/state/…` stay at the origin root. Document-relative bases (`""` and `"./"`) resolve assets beneath each nested prerendered page directory. Use `/` or a root-absolute path base — see "Sub-path deploys" below.
 
 The build also warns — without failing — on a `fallback` document in an app with no `notFound` page and no unshadowed client-routable SPA catch-all (unknown URLs would render blank).
 
 Non-ASCII `getStaticPaths()` params are written to their decoded output path (`/posts/caf%C3%A9` → `posts/café/index.html`), matching how static hosts resolve requests. Escapes that would decode into a path separator, a relative segment, or the reserved `_pracht/` namespace fail the build.
 
+## Sub-path deploys
+
+Set Vite's `base` to deploy under a path instead of an origin root — a GitHub Pages *project* site, an S3 key prefix, a reverse-proxy mount:
+
+```ts
+export default defineConfig({
+  base: "/my-project/",
+  plugins: [pracht({ adapter: staticAdapter() })],
+});
+```
+
+The output tree is unchanged (`dist/client/about/index.html`); the base is where that directory is served. Every emitted URL carries it: scripts, styles, modulepreloads, `/_pracht/state/…` fetches, `llms.txt` links, and hrefs from `<Link route>`, `href()`, `useNavigate()`, and `prefetch()`. `pracht preview` serves the export under the same base.
+
+Hand-written root-absolute links are not rewritten — `<a href="/about">` means the origin root, as in Next's `basePath` and SvelteKit's `base`. Use `<Link route="about">` or `href("about")` for internal navigation.
+
+CDN bases and document-relative bases (`""` or `"./"`) are not supported by static exports; use `/` or a safe root-absolute path such as `/my-project/`. Repeated slashes, malformed percent escapes, and segments that decode to a path separator, `.`, `..`, NUL, or a control character fail the build.
+
 ## Client-side navigation
 
-SSG loaders run at build time. For each full-hydration SSG route whose loader or route/shell `head()` metadata participates in client navigation, the build serializes route-state JSON under `dist/client/_pracht/state/` using bounded, collision-safe opaque path components, and the client router (compiled with `__PRACHT_STATIC_TARGET__`) fetches that file instead of the live route-state endpoint. Equivalent URL segment spellings (raw Unicode, lowercase percent escapes, and escaped unreserved characters) resolve to the same state file. Explicitly loaderless and headless routes fetch no Pracht state; loaderless routes with head metadata fetch static state for font-head fragments while their components and data remain browser-only. Navigation therefore stays client-side on a dumb static host.
+SSG loaders run at build time. For each full-hydration SSG route whose loader or route/shell `head()` metadata participates in client navigation, the build serializes route-state JSON under `dist/client/_pracht/state/` using bounded, collision-safe opaque path components, and the client router (compiled with `__PRACHT_STATIC_TARGET__`) fetches that file instead of the live route-state endpoint. Equivalent URL segment spellings (raw Unicode, lowercase percent escapes, and escaped unreserved characters) resolve to the same state file. Explicitly loaderless and headless routes fetch no Pracht state; loaderless routes with head metadata fetch static state for font-head fragments while their components and data remain browser-only. Dynamic routes with no `getStaticPaths()` export — the usual dynamic `render: "spa"` shape — are prerendered for no path, so the client skips a request that could never hit a file. Navigation therefore stays client-side on a dumb static host.
 
 ## Output conventions
 

package/dist/index.d.mts

@@ -49,6 +49,13 @@ interface StaticPreviewHandlerOptions {
    * are answered with `404.html` (status 404) when it exists.
    */
   fallback?: string | null;
+  /**
+   * Deploy base (Vite `base`), e.g. `"/my-project/"`. Requests below it are
+   * served from `staticDir`; the bare base redirects to it with a trailing
+   * slash, and anything outside it 404s — which is what a host serving the
+   * export under a sub-path does.
+   */
+  base?: string | null;
 }
 /**
  * A deliberately tiny static file server for `pracht preview` of static

package/dist/index.mjs

@@ -46,7 +46,7 @@ function createStaticServerEntryModule(options = {}) {
 		"  const response = await handlePrachtRequest({",
 		"    app: staticNotFoundApp,",
 		"    registry,",
-		"    request: new Request(\"http://localhost/404.html\", { method: \"GET\" }),",
+		"    request: new Request(new URL(\"404.html\", new URL(buildBase, \"http://localhost\")), { method: \"GET\" }),",
 		"    clientEntryUrl: clientEntryUrl ?? undefined,",
 		"    islandsEntryUrl: islandsEntryUrl ?? undefined,",
 		"    islandsBootstrapRequired,",
@@ -87,6 +87,7 @@ function createStaticServerEntryModule(options = {}) {
 		"  const handler = createStaticPreviewHandler({",
 		"    staticDir: resolve(serverDir, \"../client\"),",
 		"    fallback: staticExportConfig.fallback,",
+		"    base: buildBase,",
 		"  });",
 		"  const server = createServer(handler);",
 		`  const port = Number(process.env.PORT ?? ${port});`,
@@ -141,6 +142,8 @@ function staticAdapter(options = {}) {
 function createStaticPreviewHandler(options) {
 	const staticDir = resolve(options.staticDir);
 	const fallback = options.fallback ?? null;
+	const base = normalizePreviewBase(options.base);
+	const decodedBase = decodeStaticPreviewPathname(new URL(base, "http://localhost").pathname);
 	return async function handleStaticPreviewRequest(req, res) {
 		const method = req.method ?? "GET";
 		if (method !== "GET" && method !== "HEAD") {
@@ -152,14 +155,29 @@ function createStaticPreviewHandler(options) {
 			return;
 		}
 		let pathname;
+		let search;
 		try {
-			const encodedPathname = new URL(req.url ?? "/", "http://localhost").pathname;
-			pathname = decodeStaticPreviewPathname(encodedPathname);
+			const requestUrl = new URL(req.url ?? "/", "http://localhost");
+			pathname = decodeStaticPreviewPathname(requestUrl.pathname);
+			search = requestUrl.search;
 		} catch {
 			res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
 			res.end("Bad request");
 			return;
 		}
+		if (decodedBase !== "/") {
+			if (pathname === decodedBase.slice(0, -1)) {
+				res.writeHead(301, { location: `${base}${search}` });
+				res.end();
+				return;
+			}
+			if (!pathname.startsWith(decodedBase)) {
+				res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+				res.end("Not found");
+				return;
+			}
+			pathname = `/${pathname.slice(decodedBase.length)}`;
+		}
 		const file = await resolveStaticFile(staticDir, pathname);
 		if (file) {
 			await sendFile(res, method, file.filePath, file.contentType, file.cacheControl, 200);
@@ -208,5 +226,11 @@ async function sendFile(res, method, filePath, contentType, cacheControl, status
 	});
 	res.end(method === "HEAD" ? void 0 : body);
 }
+/** Vite normalizes `base` to leading and trailing slashes; be defensive anyway. */
+function normalizePreviewBase(raw) {
+	if (typeof raw !== "string" || raw === "" || raw === "/") return "/";
+	const withLeadingSlash = raw.startsWith("/") ? raw : `/${raw}`;
+	return withLeadingSlash.endsWith("/") ? withLeadingSlash : `${withLeadingSlash}/`;
+}
 //#endregion
 export { createStaticPreviewHandler, createStaticServerEntryModule, staticAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/adapter-static",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "Static-export adapter for Pracht: prerender every route and deploy dist/client to any static host with zero server.",
   "keywords": [
     "pracht",
@@ -33,12 +33,11 @@
     }
   },
   "publishConfig": {
-    "provenance": false,
-    "access": "public"
+    "provenance": true
   },
   "dependencies": {
-    "@pracht/adapter-node": "0.3.9",
-    "@pracht/core": "0.13.0"
+    "@pracht/adapter-node": "0.4.1",
+    "@pracht/core": "0.15.0"
   },
   "scripts": {
     "build": "tsdown"