@pracht/adapter-static 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jovi De Croock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @pracht/adapter-static
+
+Pure static export for pracht — the `adapter-static` / `output: "export"` of the framework. `pracht build` prerenders every route into `dist/client/`, and that directory deploys to any static host (GitHub Pages, S3, nginx, Netlify) with zero server.
+
+## Install
+
+```bash
+npm install @pracht/adapter-static
+```
+
+## Usage
+
+```ts
+// vite.config.ts
+import { pracht } from "@pracht/vite-plugin";
+import { staticAdapter } from "@pracht/adapter-static";
+
+export default {
+  plugins: [pracht({ adapter: staticAdapter() })],
+};
+```
+
+Then:
+
+```bash
+pracht build      # writes the deployable site to dist/client/
+pracht preview    # serves dist/client/ locally with a tiny static file server
+```
+
+## What must hold
+
+A static export has no server, so the build fails closed on anything that needs one:
+
+- Every route must be `render: "ssg"` or loaderless, full-hydration `"spa"`. SSG loaders run at build time and must produce HTML plus valid JSON route state; loader redirects/errors, successful non-HTML responses, malformed route-state responses, and dynamic SSG routes without `getStaticPaths()` fail the build. Render failures report the underlying error, which the rendered 500 response itself withholds. SPA loaders, non-full SPA hydration, `ssr`, and `isg` are build errors naming the routes; use browser-side fetching for live SPA data or use `@pracht/adapter-node`, `@pracht/adapter-cloudflare`, or `@pracht/adapter-vercel`.
+- Route and not-found middleware are build errors because no request runtime exists to enforce them.
+- The `notFound` page must use full hydration (the default). A static host serves the same prebuilt `404.html` for every miss, so the full client router is required to adopt the visitor's actual URL.
+- 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.
+
+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.
+
+## 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.
+
+## Output conventions
+
+- Pages: `<path>/index.html` at the percent-decoded path (clean URLs — hosts must serve `index.html` for directory URLs). `pracht preview` decodes request segments to the same filesystem spelling.
+- Route state: bounded, collision-safe opaque `.json` files under `_pracht/state/` (`/` uses `_pracht/state/index.json`). Files copied from `public/` may not occupy a generated state path; the build rejects them instead of overwriting them.
+- `404.html`: the app's `notFound` page, rendered independently of ordinary route matching at build time (GitHub Pages / S3 error-document convention).
+- `200.html` (opt-in via `staticAdapter({ fallback: "200.html" })`): SPA fallback document for hosts that can rewrite unmatched URLs; required for deep links into dynamic `render: "spa"` routes.
+
+Files copied from `public/` or emitted by Vite may not occupy the generated
+`404.html` or configured fallback path, including a case- or
+Unicode-normalization-equivalent spelling; the build rejects those portable
+collisions instead of overwriting existing output.
+
+One fallback file is shared by every rewritten URL, so it cannot evaluate a
+dynamic route or shell `head()` export. When those exports exist, provide
+explicit generic metadata shared by every fallback URL:
+
+```ts
+staticAdapter({
+  fallback: "200.html",
+  fallbackHead: { title: "My app", meta: [{ name: "robots", content: "noindex" }] },
+});
+```
+
+The build fails closed if a dynamic SPA route, its shell, or the not-found page
+exports `head()` and `fallbackHead` is omitted.
+
+Fonts in `fallbackHead` remain registered while the fallback commits a
+loaderless dynamic SPA route.
+
+The fallback only boots matched SPA routes. Paths matching a dynamic SSG route but omitted by `getStaticPaths()` render the app's `notFound` page rather than running without build-time loader state. When the fallback renders `notFound`, it reuses the loader data or handled error state serialized into `404.html`; the loader does not run again.
+
+Fallback names may not collide with `index.html` or `404.html`, including case variants on case-insensitive filesystems, use a Windows reserved device name, or exceed the portable 255-byte/code-unit component limit.
+Prerendered pages must also map to distinct portable filesystem paths. The build rejects duplicate, case-folded, and Unicode-normalization-equivalent outputs; Windows-invalid or overlong filename components; file/directory conflicts such as `/` with `/index.html`; and route directories that occupy `404.html` or the configured fallback file path before writing any page.
+
+A host rewrite to the fallback answers unknown URLs with status 200, so they become soft 404s even though the client renders the `notFound` page. Skip `fallback` when correct 404 statuses matter more than deep links into dynamic SPA routes.
+
+See `docs/ADAPTERS.md` in the repository for the full documentation, host configuration notes, and limitations.

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+import { HeadMetadata } from "@pracht/core";
+import { PrachtAdapter } from "@pracht/vite-plugin";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region src/static-entry.d.ts
+interface StaticAdapterOptions {
+  /**
+   * Additionally emit a SPA fallback document at `dist/client/<fallback>`
+   * (conventionally `"200.html"`). Configure your static host to rewrite
+   * unmatched URLs to it so deep links into non-prerendered paths (dynamic
+   * `render: "spa"` routes) boot the client router. Without a host rewrite
+   * the file is inert.
+   */
+  fallback?: string;
+  /**
+   * Metadata for the shared SPA fallback document. Every rewritten URL gets
+   * this same head because route, shell, and not-found `head()` exports run on
+   * the server and cannot be resolved for an arbitrary URL in a static document.
+   */
+  fallbackHead?: HeadMetadata;
+  /** Port used by `pracht preview` / running the generated entry directly. Defaults to 3000. */
+  port?: number;
+}
+declare function createStaticServerEntryModule(options?: StaticAdapterOptions): string;
+/**
+ * Create a pracht adapter for pure static export.
+ *
+ * ```ts
+ * import { staticAdapter } from "@pracht/adapter-static";
+ * pracht({ adapter: staticAdapter() })
+ * ```
+ *
+ * `pracht build` prerenders every route into `dist/client/` — deploy that
+ * directory to any static host. Build-time validation fails closed on
+ * anything that needs a server: `render: "ssr"` / `"isg"` routes, SPA
+ * loaders, request middleware, API routes, and network-exposed capabilities.
+ * SSG loaders run at build time; static SPA routes are loaderless.
+ */
+declare function staticAdapter(options?: StaticAdapterOptions): PrachtAdapter;
+//#endregion
+//#region src/static-preview.d.ts
+interface StaticPreviewHandlerOptions {
+  /** Directory to serve, usually `dist/client`. */
+  staticDir: string;
+  /**
+   * SPA fallback file name (e.g. `"200.html"`). When set and present in
+   * `staticDir`, unmatched URLs are answered with its contents and status
+   * 200 — mirroring a host-level rewrite rule. When unset, unmatched URLs
+   * are answered with `404.html` (status 404) when it exists.
+   */
+  fallback?: string | null;
+}
+/**
+ * A deliberately tiny static file server for `pracht preview` of static
+ * exports. It mirrors what a plain static host does — files, clean-URL
+ * `index.html` resolution, `404.html` for misses, an optional SPA fallback —
+ * and nothing else: no route matching, no loaders, no framework runtime.
+ * Production deploys should use a real static host; this exists so the build
+ * output can be exercised locally with one command.
+ */
+declare function createStaticPreviewHandler(options: StaticPreviewHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//#endregion
+export { type StaticAdapterOptions, type StaticPreviewHandlerOptions, createStaticPreviewHandler, createStaticServerEntryModule, staticAdapter };

package/dist/index.mjs

@@ -0,0 +1,212 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { resolveStaticFile } from "@pracht/adapter-node";
+//#region src/static-entry.ts
+const FALLBACK_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.html$/;
+const WINDOWS_RESERVED_FALLBACK_NAME_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const PORTABLE_FALLBACK_NAME_MAX_LENGTH = 255;
+function assertValidStaticAdapterOptions(options) {
+	const fallback = options.fallback;
+	if (fallback === void 0) {
+		if (options.fallbackHead !== void 0) throw new Error("staticAdapter({ fallbackHead }) requires a fallback file.");
+		return;
+	}
+	const normalizedFallback = fallback.toLowerCase();
+	if (normalizedFallback === "index.html" || normalizedFallback === "404.html") throw new Error(`staticAdapter({ fallback: ${JSON.stringify(fallback)} }) collides with a reserved output file — "index.html" is the root route and "404.html" is the rendered not-found page. Use "200.html".`);
+	if (!FALLBACK_FILENAME_RE.test(fallback)) throw new Error(`staticAdapter({ fallback }) expects a plain HTML file name such as "200.html", got ${JSON.stringify(fallback)}.`);
+	if (WINDOWS_RESERVED_FALLBACK_NAME_RE.test(fallback) || fallback.length > PORTABLE_FALLBACK_NAME_MAX_LENGTH || Buffer.byteLength(fallback, "utf-8") > PORTABLE_FALLBACK_NAME_MAX_LENGTH) throw new Error(`staticAdapter({ fallback: ${JSON.stringify(fallback)} }) is not a portable file name. Avoid Windows reserved device names and names longer than 255 bytes/code units.`);
+}
+function createStaticServerEntryModule(options = {}) {
+	assertValidStaticAdapterOptions(options);
+	const fallback = options.fallback ?? null;
+	const fallbackHead = options.fallbackHead ?? null;
+	const port = options.port ?? 3e3;
+	return [
+		"",
+		"// ---- @pracht/adapter-static ------------------------------------------",
+		"// A static export has no runtime server: dist/client is the deployable",
+		"// artifact. Everything below exists for `pracht build` (which imports",
+		"// this bundle to prerender) and `pracht preview` (which runs this file",
+		"// directly to serve dist/client locally).",
+		"",
+		`export const staticExportConfig = { fallback: ${JSON.stringify(fallback)}, fallbackHead: ${JSON.stringify(fallbackHead)} };`,
+		"",
+		"// Remove ordinary routes from the build-only not-found app so a broad",
+		"// dynamic pattern (`/:slug`, `/*`) cannot consume the synthetic request",
+		"// before the app-level notFound page runs. `hrefRoutes` keeps the real",
+		"// table available to `<Link route=…>`/`href()` in the shell and the",
+		"// not-found page — they are not matched, only resolved.",
+		"const staticNotFoundApp = { ...resolvedApp, routes: [], hrefRoutes: resolvedApp.routes };",
+		"",
+		"// Rendered to dist/client/404.html (the GitHub Pages / S3 error-document",
+		"// convention). Returns null when the app declares none.",
+		"export async function renderStaticNotFoundHtml() {",
+		"  if (!resolvedApp.notFound) return null;",
+		"  let renderError;",
+		"  const response = await handlePrachtRequest({",
+		"    app: staticNotFoundApp,",
+		"    registry,",
+		"    request: new Request(\"http://localhost/404.html\", { method: \"GET\" }),",
+		"    clientEntryUrl: clientEntryUrl ?? undefined,",
+		"    islandsEntryUrl: islandsEntryUrl ?? undefined,",
+		"    islandsBootstrapRequired,",
+		"    cssManifest,",
+		"    jsManifest,",
+		"    onRouteError: (error) => {",
+		"      renderError = error;",
+		"    },",
+		"  });",
+		"  const contentType = response.headers.get(\"content-type\") ?? \"\";",
+		"  if (response.status !== 404) {",
+		"    const location = response.headers.get(\"location\");",
+		"    const detail = location ? ` (redirect: ${location})` : \"\";",
+		"    throw new Error(",
+		"      `Static export failed to render the notFound page: status ${response.status}${detail}. Make its loader succeed at build time or use a serverful adapter.` +",
+		"        describeRenderError(renderError),",
+		"      renderError === undefined ? undefined : { cause: renderError },",
+		"    );",
+		"  }",
+		"  if (!contentType.includes(\"text/html\")) {",
+		"    throw new Error(`Static export failed to render the notFound page as HTML (content-type: ${contentType || \"missing\"}).`);",
+		"  }",
+		"  return await response.text();",
+		"}",
+		"",
+		"export function renderStaticFallbackHtml(notFoundState) {",
+		"  return buildStaticFallbackHtml({",
+		"    clientEntryUrl: clientEntryUrl ?? undefined,",
+		"    head: staticExportConfig.fallbackHead ?? undefined,",
+		"    notFoundData: notFoundState?.data,",
+		"    notFoundError: notFoundState?.error ?? null,",
+		"  });",
+		"}",
+		"",
+		"const entryHref = process.argv[1] ? pathToFileURL(process.argv[1]).href : null;",
+		"if (entryHref && import.meta.url === entryHref) {",
+		"  const serverDir = dirname(fileURLToPath(import.meta.url));",
+		"  const handler = createStaticPreviewHandler({",
+		"    staticDir: resolve(serverDir, \"../client\"),",
+		"    fallback: staticExportConfig.fallback,",
+		"  });",
+		"  const server = createServer(handler);",
+		`  const port = Number(process.env.PORT ?? ${port});`,
+		"  server.listen(port, () => {",
+		"    console.log(`pracht static preview listening on http://localhost:${port}`);",
+		"  });",
+		"}",
+		""
+	].join("\n");
+}
+/**
+* Create a pracht adapter for pure static export.
+*
+* ```ts
+* import { staticAdapter } from "@pracht/adapter-static";
+* pracht({ adapter: staticAdapter() })
+* ```
+*
+* `pracht build` prerenders every route into `dist/client/` — deploy that
+* directory to any static host. Build-time validation fails closed on
+* anything that needs a server: `render: "ssr"` / `"isg"` routes, SPA
+* loaders, request middleware, API routes, and network-exposed capabilities.
+* SSG loaders run at build time; static SPA routes are loaderless.
+*/
+function staticAdapter(options = {}) {
+	assertValidStaticAdapterOptions(options);
+	return {
+		id: "static",
+		staticTarget: true,
+		serverImports: [
+			"import { createServer } from \"node:http\";",
+			"import { dirname, resolve } from \"node:path\";",
+			"import { fileURLToPath, pathToFileURL } from \"node:url\";",
+			"import { resolveApp, resolveApiRoutes, handlePrachtRequest, buildStaticFallbackHtml, describeRenderError } from \"@pracht/core/server\";",
+			"import { createStaticPreviewHandler } from \"@pracht/adapter-static\";"
+		].join("\n"),
+		createServerEntryModule() {
+			return createStaticServerEntryModule(options);
+		}
+	};
+}
+//#endregion
+//#region src/static-preview.ts
+/**
+* A deliberately tiny static file server for `pracht preview` of static
+* exports. It mirrors what a plain static host does — files, clean-URL
+* `index.html` resolution, `404.html` for misses, an optional SPA fallback —
+* and nothing else: no route matching, no loaders, no framework runtime.
+* Production deploys should use a real static host; this exists so the build
+* output can be exercised locally with one command.
+*/
+function createStaticPreviewHandler(options) {
+	const staticDir = resolve(options.staticDir);
+	const fallback = options.fallback ?? null;
+	return async function handleStaticPreviewRequest(req, res) {
+		const method = req.method ?? "GET";
+		if (method !== "GET" && method !== "HEAD") {
+			res.writeHead(405, {
+				"content-type": "text/plain; charset=utf-8",
+				allow: "GET, HEAD"
+			});
+			res.end("Method not allowed");
+			return;
+		}
+		let pathname;
+		try {
+			const encodedPathname = new URL(req.url ?? "/", "http://localhost").pathname;
+			pathname = decodeStaticPreviewPathname(encodedPathname);
+		} catch {
+			res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+			res.end("Bad request");
+			return;
+		}
+		const file = await resolveStaticFile(staticDir, pathname);
+		if (file) {
+			await sendFile(res, method, file.filePath, file.contentType, file.cacheControl, 200);
+			return;
+		}
+		if (fallback) {
+			const fallbackFile = await resolveStaticFile(staticDir, `/${fallback}`);
+			if (fallbackFile?.filePath === resolve(staticDir, fallback)) {
+				await sendFile(res, method, fallbackFile.filePath, "text/html; charset=utf-8", "no-cache", 200);
+				return;
+			}
+		}
+		const notFoundFile = await resolveStaticFile(staticDir, "/404.html");
+		if (notFoundFile?.filePath === resolve(staticDir, "404.html")) {
+			await sendFile(res, method, notFoundFile.filePath, "text/html; charset=utf-8", "no-cache", 404);
+			return;
+		}
+		res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+		res.end("Not found");
+	};
+}
+/**
+* Decode each URL segment into the filesystem spelling emitted by the static
+* exporter without allowing an escape to introduce path structure.
+*/
+function decodeStaticPreviewPathname(pathname) {
+	return pathname.split("/").map((segment) => {
+		const decoded = decodeURIComponent(segment);
+		if (decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\") || decoded.includes("\0")) throw new Error("Unsafe encoded static path segment.");
+		return decoded;
+	}).join("/");
+}
+async function sendFile(res, method, filePath, contentType, cacheControl, status) {
+	let body;
+	try {
+		body = await readFile(filePath);
+	} catch {
+		res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+		res.end("Not found");
+		return;
+	}
+	res.writeHead(status, {
+		"content-type": contentType,
+		"cache-control": cacheControl,
+		"content-length": body.byteLength
+	});
+	res.end(method === "HEAD" ? void 0 : body);
+}
+//#endregion
+export { createStaticPreviewHandler, createStaticServerEntryModule, staticAdapter };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pracht/adapter-static",
+  "version": "0.0.0",
+  "description": "Static-export adapter for Pracht: prerender every route and deploy dist/client to any static host with zero server.",
+  "keywords": [
+    "pracht",
+    "preact",
+    "static",
+    "ssg",
+    "export",
+    "adapter",
+    "github-pages",
+    "vite"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/adapter-static",
+  "bugs": {
+    "url": "https://github.com/JoviDeCroock/pracht/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JoviDeCroock/pracht",
+    "directory": "packages/adapter-static"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "provenance": false,
+    "access": "public"
+  },
+  "dependencies": {
+    "@pracht/adapter-node": "0.3.9",
+    "@pracht/core": "0.13.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}