@pracht/core 0.0.1 → 0.2.0

package/README.md

@@ -16,11 +16,22 @@ npm install @pracht/core preact preact-render-to-string
 - `route()` — declare a route with path, component, loader, and rendering mode
 - `group()` — group routes under a shared shell or middleware
 
+Route modules may export the page as a function default export or as a named
+`Component` export. Named exports such as `loader`, `head`, `ErrorBoundary`, and
+`getStaticPaths` keep their special route-module behavior.
+
 ### Server
 
 - `handlePrachtRequest()` — server renderer that produces full HTML with hydration markers
 - `matchAppRoute()` — segment-based route matching
 
+`handlePrachtRequest()` sanitizes unexpected 5xx errors by default so raw server
+messages do not leak into SSR HTML or route-state JSON. Explicit
+`PrachtHttpError` 4xx messages are preserved. Pass `debugErrors: true` to expose
+raw details intentionally during debugging; `@pracht/core` does not infer this
+from environment variables. Debug responses also attach `error.diagnostics`
+metadata for the failure phase and matched framework files when available.
+
 ### Client
 
 - `startApp()` — client-side hydration and runtime
@@ -42,4 +53,4 @@ Each route can specify its rendering mode:
 - `ssr` — server-rendered on every request
 - `ssg` — pre-rendered at build time
 - `isg` — pre-rendered with time-based revalidation
-- `spa` — client-only rendering
+- `spa` — client-only route rendering with optional shell/loading HTML on first paint

package/dist/{app-CAoDWWNO.mjs → app-Cep0el7c.mjs}

@@ -30,21 +30,26 @@ function timeRevalidate(seconds) {
 	};
 }
 function route(path, fileOrConfig, meta = {}) {
-	if (typeof fileOrConfig === "string") return {
+	if (typeof fileOrConfig === "string" || typeof fileOrConfig === "function") return {
 		kind: "route",
 		path: normalizeRoutePath(path),
-		file: fileOrConfig,
+		file: resolveModuleRef(fileOrConfig),
 		...meta
 	};
 	const { component, loader, ...routeMeta } = fileOrConfig;
 	return {
 		kind: "route",
 		path: normalizeRoutePath(path),
-		file: component,
-		loaderFile: loader,
+		file: resolveModuleRef(component),
+		loaderFile: resolveModuleRef(loader),
 		...routeMeta
 	};
 }
+function resolveModuleRef(ref) {
+	if (ref === void 0) return void 0;
+	if (typeof ref === "string") return ref;
+	return "";
+}
 function group(meta, routes) {
 	return {
 		kind: "group",
@@ -54,12 +59,17 @@ function group(meta, routes) {
 }
 function defineApp(config) {
 	return {
-		shells: config.shells ?? {},
-		middleware: config.middleware ?? {},
+		shells: resolveModuleRefRecord(config.shells ?? {}),
+		middleware: resolveModuleRefRecord(config.middleware ?? {}),
 		api: config.api ?? {},
 		routes: config.routes
 	};
 }
+function resolveModuleRefRecord(record) {
+	const result = {};
+	for (const [key, value] of Object.entries(record)) result[key] = resolveModuleRef(value);
+	return result;
+}
 function resolveApp(app) {
 	const routes = [];
 	const inherited = {
@@ -136,7 +146,11 @@ function matchRouteSegments(routeSegments, targetSegments) {
 		if (typeof targetSegment === "undefined") return null;
 		if (currentSegment.type === "static") {
 			if (currentSegment.value !== targetSegment) return null;
-		} else params[currentSegment.name] = decodeURIComponent(targetSegment);
+		} else try {
+			params[currentSegment.name] = decodeURIComponent(targetSegment);
+		} catch {
+			return null;
+		}
 		routeIndex += 1;
 		targetIndex += 1;
 	}

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Suspense, lazy } from "preact-suspense";
 import * as _$preact from "preact";
 import { ComponentChildren, FunctionComponent, JSX, h } from "preact";
+import { Suspense, lazy } from "preact-suspense";
 
 //#region src/types.d.ts
 /**
@@ -23,6 +23,12 @@ type RegisteredContext = Register extends {
 } ? T : unknown;
 type RenderMode = "spa" | "ssr" | "ssg" | "isg";
 type RouteParams = Record<string, string>;
+/**
+ * A reference to a module file — either a plain string path or a lazy import
+ * function. Using `() => import("./path")` enables IDE click-to-navigate.
+ * The vite plugin transforms import functions back to strings at build time.
+ */
+type ModuleRef = string | (() => Promise<any>);
 interface TimeRevalidatePolicy {
   kind: "time";
   seconds: number;
@@ -68,8 +74,8 @@ interface ApiConfig {
   middleware?: string[];
 }
 interface RouteConfig extends RouteMeta {
-  component: string;
-  loader?: string;
+  component: ModuleRef;
+  loader?: ModuleRef;
 }
 interface RouteDefinition extends RouteMeta {
   kind: "route";
@@ -84,8 +90,8 @@ interface GroupDefinition {
 }
 type RouteTreeNode = RouteDefinition | GroupDefinition;
 interface PrachtAppConfig {
-  shells?: Record<string, string>;
-  middleware?: Record<string, string>;
+  shells?: Record<string, ModuleRef>;
+  middleware?: Record<string, ModuleRef>;
   api?: ApiConfig;
   routes: RouteTreeNode[];
 }
@@ -163,12 +169,14 @@ type LoaderFn<TContext = any, TData = unknown> = (args: LoaderArgs<TContext>) =>
 interface RouteModule<TContext = any, TLoader extends LoaderLike = undefined> {
   loader?: LoaderFn<TContext>;
   head?: (args: HeadArgs<TLoader, TContext>) => MaybePromise<HeadMetadata>;
-  Component: FunctionComponent<RouteComponentProps<TLoader>>;
+  Component?: FunctionComponent<RouteComponentProps<TLoader>>;
+  default?: FunctionComponent<RouteComponentProps<TLoader>>;
   ErrorBoundary?: FunctionComponent<ErrorBoundaryProps>;
   getStaticPaths?: () => MaybePromise<RouteParams[]>;
 }
 interface ShellModule<TContext = any> {
   Shell: FunctionComponent<ShellProps>;
+  Loading?: FunctionComponent;
   head?: (args: BaseRouteArgs<TContext>) => MaybePromise<HeadMetadata>;
 }
 type MiddlewareResult<TContext = any> = void | Response | {
@@ -198,7 +206,7 @@ declare class PrachtHttpError extends Error {
 //#endregion
 //#region src/app.d.ts
 declare function timeRevalidate(seconds: number): TimeRevalidatePolicy;
-declare function route(path: string, file: string, meta?: RouteMeta): RouteDefinition;
+declare function route(path: string, file: ModuleRef, meta?: RouteMeta): RouteDefinition;
 declare function route(path: string, config: RouteConfig): RouteDefinition;
 declare function group(meta: GroupMeta, routes: RouteTreeNode[]): GroupDefinition;
 declare function defineApp(config: PrachtAppConfig): PrachtApp;
@@ -215,17 +223,50 @@ declare function buildPathFromSegments(segments: RouteSegment[], params: RoutePa
 declare function resolveApiRoutes(files: string[], apiDir?: string): ResolvedApiRoute[];
 declare function matchApiRoute(apiRoutes: ResolvedApiRoute[], pathname: string): ApiRouteMatch | undefined;
 //#endregion
+//#region src/forwardRef.d.ts
+/**
+ * Pass ref down to a child. This is mainly used in libraries with HOCs that
+ * wrap components. Using `forwardRef` there is an easy way to get a reference
+ * of the wrapped component instead of one of the wrapper itself.
+ */
+declare function forwardRef<P = {}>(fn: ((props: P, ref: any) => any) & {
+  displayName?: string;
+}): FunctionComponent<P & {
+  ref?: any;
+}>;
+//#endregion
+//#region src/hydration.d.ts
+/**
+ * Returns `true` once the initial hydration (including all Suspense
+ * boundaries) has fully resolved. During SSR and hydration this returns
+ * `false`.
+ */
+declare function useIsHydrated(): boolean;
+//#endregion
 //#region src/runtime.d.ts
+type PrachtRuntimeDiagnosticPhase = "match" | "middleware" | "loader" | "action" | "render" | "api";
+interface PrachtRuntimeDiagnostics {
+  phase: PrachtRuntimeDiagnosticPhase;
+  routeId?: string;
+  routePath?: string;
+  routeFile?: string;
+  loaderFile?: string;
+  shellFile?: string;
+  middlewareFiles?: string[];
+  status: number;
+}
 interface PrachtHydrationState<TData = unknown> {
   url: string;
   routeId: string;
   data: TData;
   error?: SerializedRouteError | null;
+  pending?: boolean;
 }
 interface SerializedRouteError {
   message: string;
   name: string;
   status: number;
+  diagnostics?: PrachtRuntimeDiagnostics;
 }
 interface StartAppOptions<TData = unknown> {
   initialData?: TData;
@@ -235,6 +276,8 @@ interface HandlePrachtRequestOptions<TContext = unknown> {
   request: Request;
   context?: TContext;
   registry?: ModuleRegistry;
+  /** Expose raw server error details in rendered HTML and route-state JSON. */
+  debugErrors?: boolean;
   clientEntryUrl?: string;
   /** Per-source-file CSS map produced by the vite plugin (preferred over cssUrls). */
   cssManifest?: Record<string, string[]>;
@@ -291,6 +334,16 @@ declare function useRevalidate(): () => Promise<unknown>;
 /** @deprecated Use useRevalidate instead. */
 declare const useRevalidateRoute: typeof useRevalidate;
 declare function Form(props: FormProps): _$preact.VNode<_$preact.ClassAttributes<HTMLFormElement> & h.JSX.HTMLAttributes<HTMLFormElement>>;
+type RouteStateResult = {
+  type: "data";
+  data: unknown;
+} | {
+  type: "redirect";
+  location: string;
+} | {
+  type: "error";
+  error: SerializedRouteError;
+};
 declare function handlePrachtRequest<TContext>(options: HandlePrachtRequestOptions<TContext>): Promise<Response>;
 declare function applyDefaultSecurityHeaders(headers: Headers): Headers;
 interface PrerenderResult {
@@ -340,4 +393,4 @@ interface InitClientRouterOptions {
 }
 declare function initClientRouter(options: InitClientRouterOptions): Promise<void>;
 //#endregion
-export { type ApiConfig, type ApiRouteHandler, type ApiRouteMatch, type ApiRouteModule, type BaseRouteArgs, type DataModule, type ErrorBoundaryProps, Form, type FormProps, type GroupDefinition, type GroupMeta, type HandlePrachtRequestOptions, type HeadArgs, type HeadMetadata, type HttpMethod, type ISGManifestEntry, type InitClientRouterOptions, type LoaderArgs, type LoaderData, type LoaderFn, type Location, type MiddlewareArgs, type MiddlewareFn, type MiddlewareModule, type MiddlewareResult, type ModuleImporter, type ModuleRegistry, type NavigateFn, type PrachtApp, type PrachtAppConfig, PrachtHttpError, type PrachtHydrationState, PrachtRuntimeProvider, type PrefetchStrategy, type PrerenderAppOptions, type PrerenderAppResult, type PrerenderResult, type Register, type RenderMode, type ResolvedApiRoute, type ResolvedPrachtApp, type ResolvedRoute, type RouteComponentProps, type RouteConfig, type RouteDefinition, type RouteMatch, type RouteMeta, type RouteModule, type RouteParams, type RouteRevalidate, type RouteTreeNode, type ShellModule, type ShellProps, type StartAppOptions, Suspense, type TimeRevalidatePolicy, applyDefaultSecurityHeaders, buildPathFromSegments, defineApp, group, handlePrachtRequest, initClientRouter, lazy, matchApiRoute, matchAppRoute, prerenderApp, readHydrationState, resolveApiRoutes, resolveApp, route, startApp, timeRevalidate, useLocation, useNavigate, useParams, useRevalidate, useRevalidateRoute, useRouteData };
+export { type ApiConfig, type ApiRouteHandler, type ApiRouteMatch, type ApiRouteModule, type BaseRouteArgs, type DataModule, type ErrorBoundaryProps, Form, type FormProps, type GroupDefinition, type GroupMeta, type HandlePrachtRequestOptions, type HeadArgs, type HeadMetadata, type HttpMethod, type ISGManifestEntry, type InitClientRouterOptions, type LoaderArgs, type LoaderData, type LoaderFn, type Location, type MiddlewareArgs, type MiddlewareFn, type MiddlewareModule, type MiddlewareResult, type ModuleImporter, type ModuleRef, type ModuleRegistry, type NavigateFn, type PrachtApp, type PrachtAppConfig, PrachtHttpError, type PrachtHydrationState, type PrachtRuntimeDiagnosticPhase, type PrachtRuntimeDiagnostics, PrachtRuntimeProvider, type PrefetchStrategy, type PrerenderAppOptions, type PrerenderAppResult, type PrerenderResult, type Register, type RenderMode, type ResolvedApiRoute, type ResolvedPrachtApp, type ResolvedRoute, type RouteComponentProps, type RouteConfig, type RouteDefinition, type RouteMatch, type RouteMeta, type RouteModule, type RouteParams, type RouteRevalidate, type RouteStateResult, type RouteTreeNode, type SerializedRouteError, type ShellModule, type ShellProps, type StartAppOptions, Suspense, type TimeRevalidatePolicy, applyDefaultSecurityHeaders, buildPathFromSegments, defineApp, forwardRef, group, handlePrachtRequest, initClientRouter, lazy, matchApiRoute, matchAppRoute, prerenderApp, readHydrationState, resolveApiRoutes, resolveApp, route, startApp, timeRevalidate, useIsHydrated, useLocation, useNavigate, useParams, useRevalidate, useRevalidateRoute, useRouteData };

package/dist/index.mjs

@@ -1,10 +1,82 @@
-import { a as matchApiRoute, c as resolveApp, i as group, l as route, n as buildPathFromSegments, o as matchAppRoute, r as defineApp, s as resolveApiRoutes, u as timeRevalidate } from "./app-CAoDWWNO.mjs";
-import { Suspense, lazy } from "preact-suspense";
-import { createContext, h, hydrate, render } from "preact";
+import { a as matchApiRoute, c as resolveApp, i as group, l as route, n as buildPathFromSegments, o as matchAppRoute, r as defineApp, s as resolveApiRoutes, u as timeRevalidate } from "./app-Cep0el7c.mjs";
+import { createContext, h, hydrate, options, render } from "preact";
 import { useContext, useEffect, useMemo, useState } from "preact/hooks";
+import { Suspense, lazy } from "preact-suspense";
+//#region src/forwardRef.ts
+let oldDiffHook = options.__b;
+options.__b = (vnode) => {
+	if (vnode.type && vnode.type.__f && vnode.ref) {
+		vnode.props.ref = vnode.ref;
+		vnode.ref = null;
+	}
+	if (oldDiffHook) oldDiffHook(vnode);
+};
+/**
+* Pass ref down to a child. This is mainly used in libraries with HOCs that
+* wrap components. Using `forwardRef` there is an easy way to get a reference
+* of the wrapped component instead of one of the wrapper itself.
+*/
+function forwardRef(fn) {
+	function Forwarded(props) {
+		const clone = { ...props };
+		delete clone.ref;
+		return fn(clone, props.ref || null);
+	}
+	Forwarded.__f = true;
+	Forwarded.displayName = "ForwardRef(" + (fn.displayName || fn.name) + ")";
+	return Forwarded;
+}
+//#endregion
+//#region src/hydration.ts
+let _hydrating = false;
+let _suspensionCount = 0;
+let _hydrated = false;
+const oldCatchError = options.__e;
+options.__e = (err, newVNode, oldVNode, errorInfo) => {
+	if (_hydrating && !_hydrated && err && err.then) {
+		_suspensionCount++;
+		let settled = false;
+		const onSettled = () => {
+			if (settled) return;
+			settled = true;
+			_suspensionCount--;
+		};
+		err.then(onSettled, onSettled);
+	}
+	if (oldCatchError) oldCatchError(err, newVNode, oldVNode, errorInfo);
+};
+const oldDiffed = options.diffed;
+options.diffed = (vnode) => {
+	if (_hydrating && !_hydrated && _suspensionCount <= 0) {
+		_hydrated = true;
+		_hydrating = false;
+	}
+	if (oldDiffed) oldDiffed(vnode);
+};
+/**
+* Mark the start of a hydration pass. Call this right before `hydrate()`.
+*/
+function markHydrating() {
+	if (!_hydrated) _hydrating = true;
+}
+/**
+* Returns `true` once the initial hydration (including all Suspense
+* boundaries) has fully resolved. During SSR and hydration this returns
+* `false`.
+*/
+function useIsHydrated() {
+	const [hydrated, setHydrated] = useState(_hydrated);
+	useEffect(() => {
+		setHydrated(true);
+	}, []);
+	return hydrated;
+}
+//#endregion
 //#region src/runtime.ts
 const SAFE_METHODS = new Set(["GET", "HEAD"]);
 const HYDRATION_STATE_ELEMENT_ID = "pracht-state";
+const ROUTE_STATE_REQUEST_HEADER = "x-pracht-route-state-request";
+const ROUTE_STATE_CACHE_CONTROL = "no-store";
 const RouteDataContext = createContext(void 0);
 function PrachtRuntimeProvider({ children, data, params = {}, routeId, url }) {
 	const [routeData, setRouteData] = useState(data);
@@ -109,7 +181,7 @@ function Form(props) {
 async function fetchPrachtRouteState(url) {
 	const response = await fetch(url, {
 		headers: {
-			"x-pracht-route-state-request": "1",
+			[ROUTE_STATE_REQUEST_HEADER]: "1",
 			"Cache-Control": "no-cache"
 		},
 		redirect: "manual"
@@ -134,6 +206,8 @@ async function fetchPrachtRouteState(url) {
 async function handlePrachtRequest(options) {
 	const url = new URL(options.request.url);
 	const registry = options.registry ?? {};
+	const isRouteStateRequest = options.request.headers.get(ROUTE_STATE_REQUEST_HEADER) === "1";
+	const exposeDiagnostics = shouldExposeServerErrors(options);
 	if (options.apiRoutes?.length) {
 		const apiMatch = matchApiRoute(options.apiRoutes, url.pathname);
 		if (apiMatch) {
@@ -141,96 +215,145 @@ async function handlePrachtRequest(options) {
 				const middlewareFile = options.app.middleware[name];
 				return middlewareFile ? [middlewareFile] : [];
 			});
-			const middlewareResult = await runMiddlewareChain({
-				context: options.context ?? {},
-				middlewareFiles: apiMiddlewareFiles,
-				params: apiMatch.params,
-				registry,
-				request: options.request,
-				route: apiMatch.route,
-				url
-			});
-			if (middlewareResult.response) return middlewareResult.response;
-			const apiModule = await resolveRegistryModule(registry.apiModules, apiMatch.route.file);
-			if (!apiModule) return withDefaultSecurityHeaders(new Response("API route module not found", {
-				status: 500,
-				headers: { "content-type": "text/plain; charset=utf-8" }
-			}));
-			const handler = apiModule[options.request.method.toUpperCase()];
-			if (!handler) return withDefaultSecurityHeaders(new Response("Method not allowed", {
-				status: 405,
-				headers: { "content-type": "text/plain; charset=utf-8" }
-			}));
-			return withDefaultSecurityHeaders(await handler({
-				request: options.request,
-				params: apiMatch.params,
-				context: middlewareResult.context,
-				signal: AbortSignal.timeout(3e4),
-				url,
-				route: apiMatch.route
-			}));
+			let currentPhase = "middleware";
+			try {
+				const middlewareResult = await runMiddlewareChain({
+					context: options.context ?? {},
+					middlewareFiles: apiMiddlewareFiles,
+					params: apiMatch.params,
+					registry,
+					request: options.request,
+					route: apiMatch.route,
+					url
+				});
+				if (middlewareResult.response) return middlewareResult.response;
+				currentPhase = "api";
+				const apiModule = await resolveRegistryModule(registry.apiModules, apiMatch.route.file);
+				if (!apiModule) throw new Error("API route module not found");
+				const handler = apiModule[options.request.method.toUpperCase()];
+				if (!handler) return withDefaultSecurityHeaders(new Response("Method not allowed", {
+					status: 405,
+					headers: { "content-type": "text/plain; charset=utf-8" }
+				}));
+				return withDefaultSecurityHeaders(await handler({
+					request: options.request,
+					params: apiMatch.params,
+					context: middlewareResult.context,
+					signal: AbortSignal.timeout(3e4),
+					url,
+					route: apiMatch.route
+				}));
+			} catch (error) {
+				return renderApiErrorResponse({
+					error,
+					middlewareFiles: apiMiddlewareFiles,
+					options,
+					phase: currentPhase,
+					route: apiMatch.route
+				});
+			}
 		}
 	}
 	const match = matchAppRoute(options.app, url.pathname);
-	if (!match) return withDefaultSecurityHeaders(new Response("Not found", {
-		status: 404,
-		headers: { "content-type": "text/plain; charset=utf-8" }
-	}));
-	const isRouteStateRequest = options.request.headers.get("x-pracht-route-state-request") === "1";
-	if (!SAFE_METHODS.has(options.request.method)) return withDefaultSecurityHeaders(new Response("Method not allowed", {
-		status: 405,
-		headers: { "content-type": "text/plain; charset=utf-8" }
-	}));
-	const middlewareResult = await runMiddlewareChain({
-		context: options.context ?? {},
-		middlewareFiles: match.route.middlewareFiles,
-		params: match.params,
-		registry,
-		request: options.request,
-		route: match.route,
-		url
-	});
-	if (middlewareResult.response) return middlewareResult.response;
-	const context = middlewareResult.context;
-	const routeModule = await resolveRegistryModule(registry.routeModules, match.route.file);
-	const routeArgs = {
+	if (!match) {
+		if (isRouteStateRequest) return jsonErrorResponse(createSerializedRouteError("Not found", 404, {
+			diagnostics: exposeDiagnostics ? buildRuntimeDiagnostics({
+				phase: "match",
+				status: 404
+			}) : void 0,
+			name: "Error"
+		}), { isRouteStateRequest: true });
+		return withDefaultSecurityHeaders(new Response("Not found", {
+			status: 404,
+			headers: { "content-type": "text/plain; charset=utf-8" }
+		}));
+	}
+	if (!SAFE_METHODS.has(options.request.method)) {
+		if (isRouteStateRequest) return jsonErrorResponse(createSerializedRouteError("Method not allowed", 405, {
+			diagnostics: exposeDiagnostics ? buildRuntimeDiagnostics({
+				middlewareFiles: match.route.middlewareFiles,
+				phase: "action",
+				route: match.route,
+				shellFile: match.route.shellFile,
+				status: 405
+			}) : void 0,
+			name: "Error"
+		}), { isRouteStateRequest: true });
+		return withRouteResponseHeaders(new Response("Method not allowed", {
+			status: 405,
+			headers: { "content-type": "text/plain; charset=utf-8" }
+		}), { isRouteStateRequest });
+	}
+	let routeArgs = {
 		request: options.request,
 		params: match.params,
-		context,
+		context: options.context ?? {},
 		signal: AbortSignal.timeout(3e4),
 		url,
 		route: match.route
 	};
-	const { loader } = await resolveDataFunctions(match.route, routeModule, registry);
+	let routeModule;
 	let shellModule;
+	let loaderFile;
+	let currentPhase = "middleware";
 	try {
+		const middlewareResult = await runMiddlewareChain({
+			context: routeArgs.context,
+			middlewareFiles: match.route.middlewareFiles,
+			params: match.params,
+			registry,
+			request: options.request,
+			route: match.route,
+			url
+		});
+		if (middlewareResult.response) return withRouteResponseHeaders(middlewareResult.response, { isRouteStateRequest });
+		routeArgs = {
+			...routeArgs,
+			context: middlewareResult.context
+		};
+		currentPhase = "render";
+		routeModule = await resolveRegistryModule(registry.routeModules, match.route.file);
+		if (!routeModule) throw new Error("Route module not found");
+		currentPhase = "loader";
+		const { loader, loaderFile: resolvedLoaderFile } = await resolveDataFunctions(match.route, routeModule, registry);
+		loaderFile = resolvedLoaderFile;
 		const loaderResult = loader ? await loader(routeArgs) : void 0;
-		if (loaderResult instanceof Response) return withDefaultSecurityHeaders(loaderResult);
+		if (loaderResult instanceof Response) return withRouteResponseHeaders(loaderResult, { isRouteStateRequest });
 		const data = loaderResult;
-		if (isRouteStateRequest) return withDefaultSecurityHeaders(Response.json({ data }));
+		if (isRouteStateRequest) return withRouteResponseHeaders(Response.json({ data }), { isRouteStateRequest: true });
+		currentPhase = "render";
 		shellModule = match.route.shellFile ? await resolveRegistryModule(registry.shellModules, match.route.shellFile) : void 0;
 		const head = await mergeHeadMetadata(shellModule, routeModule, routeArgs, data);
 		const cssUrls = resolvePageCssUrls(options, match.route.shellFile, match.route.file);
 		const modulePreloadUrls = resolvePageJsUrls(options, match.route.shellFile, match.route.file);
-		if (match.route.render === "spa") return htmlResponse(buildHtmlDocument({
-			head,
-			body: "",
-			hydrationState: {
-				url: url.pathname,
-				routeId: match.route.id ?? "",
-				data: null,
-				error: null
-			},
-			clientEntryUrl: options.clientEntryUrl,
-			cssUrls,
-			modulePreloadUrls
-		}));
-		if (!routeModule?.Component) return withDefaultSecurityHeaders(new Response("Route has no Component export", {
-			status: 500,
-			headers: { "content-type": "text/plain; charset=utf-8" }
-		}));
+		if (match.route.render === "spa") {
+			let body = "";
+			if (shellModule?.Shell || shellModule?.Loading) {
+				const { renderToStringAsync } = await import("preact-render-to-string");
+				const Shell = shellModule?.Shell;
+				const Loading = shellModule?.Loading;
+				const loadingTree = Shell != null ? h(Shell, null, Loading ? h(Loading, null) : null) : Loading ? h(Loading, null) : null;
+				if (loadingTree) body = await renderToStringAsync(loadingTree);
+			}
+			return htmlResponse(buildHtmlDocument({
+				head,
+				body,
+				hydrationState: {
+					url: url.pathname,
+					routeId: match.route.id ?? "",
+					data: null,
+					error: null,
+					pending: true
+				},
+				clientEntryUrl: options.clientEntryUrl,
+				cssUrls,
+				modulePreloadUrls
+			}));
+		}
+		const DefaultComponent = typeof routeModule.default === "function" ? routeModule.default : void 0;
+		const Component = routeModule.Component ?? DefaultComponent;
+		if (!Component) throw new Error("Route has no Component or default export");
 		const { renderToStringAsync } = await import("preact-render-to-string");
-		const Component = routeModule.Component;
 		const Shell = shellModule?.Shell;
 		const componentProps = {
 			data,
@@ -259,7 +382,9 @@ async function handlePrachtRequest(options) {
 		return renderRouteErrorResponse({
 			error,
 			isRouteStateRequest,
+			loaderFile,
 			options,
+			phase: currentPhase,
 			routeArgs,
 			routeId: match.route.id ?? "",
 			routeModule,
@@ -314,15 +439,65 @@ async function navigateToClientLocation(location, options) {
 function isPrachtHttpError(error) {
 	return error instanceof Error && error.name === "PrachtHttpError" && "status" in error;
 }
-function normalizeRouteError(error) {
-	if (isPrachtHttpError(error)) return {
-		message: error.message,
-		name: error.name,
-		status: typeof error.status === "number" ? error.status : 500
+function shouldExposeServerErrors(options) {
+	return options.debugErrors === true;
+}
+function createSerializedRouteError(message, status, options = {}) {
+	return {
+		message,
+		name: options.name ?? "Error",
+		status,
+		...options.diagnostics ? { diagnostics: options.diagnostics } : {}
+	};
+}
+function buildRuntimeDiagnostics(options) {
+	const route = options.route;
+	const routeId = route && "id" in route ? route.id : void 0;
+	return {
+		phase: options.phase,
+		routeId,
+		routePath: route?.path,
+		routeFile: route?.file,
+		loaderFile: options.loaderFile,
+		shellFile: options.shellFile,
+		middlewareFiles: options.middlewareFiles ? [...options.middlewareFiles] : [],
+		status: options.status
 	};
-	if (error instanceof Error) return {
-		message: error.message || "Internal Server Error",
-		name: error.name || "Error",
+}
+function normalizeRouteError(error, options) {
+	if (isPrachtHttpError(error)) {
+		const status = typeof error.status === "number" ? error.status : 500;
+		if (status >= 400 && status < 500) return {
+			message: error.message,
+			name: error.name,
+			status
+		};
+		if (options.exposeDetails) return {
+			message: error.message || "Internal Server Error",
+			name: error.name || "Error",
+			status
+		};
+		return {
+			message: "Internal Server Error",
+			name: "Error",
+			status
+		};
+	}
+	if (error instanceof Error) {
+		if (options.exposeDetails) return {
+			message: error.message || "Internal Server Error",
+			name: error.name || "Error",
+			status: 500
+		};
+		return {
+			message: "Internal Server Error",
+			name: "Error",
+			status: 500
+		};
+	}
+	if (options.exposeDetails) return {
+		message: typeof error === "string" && error ? error : "Internal Server Error",
+		name: "Error",
 		status: 500
 	};
 	return {
@@ -335,25 +510,58 @@ function deserializeRouteError$1(error) {
 	const result = new Error(error.message);
 	result.name = error.name;
 	result.status = error.status;
+	result.diagnostics = error.diagnostics;
 	return result;
 }
+function jsonErrorResponse(routeError, options) {
+	const response = new Response(JSON.stringify({ error: routeError }), {
+		status: routeError.status,
+		headers: { "content-type": "application/json; charset=utf-8" }
+	});
+	return options.isRouteStateRequest ? withRouteResponseHeaders(response, { isRouteStateRequest: true }) : withDefaultSecurityHeaders(response);
+}
+function renderApiErrorResponse(options) {
+	const exposeDetails = shouldExposeServerErrors(options.options);
+	const routeError = normalizeRouteError(options.error, { exposeDetails });
+	const routeErrorWithDiagnostics = exposeDetails ? {
+		...routeError,
+		diagnostics: buildRuntimeDiagnostics({
+			middlewareFiles: options.middlewareFiles,
+			phase: options.phase,
+			route: options.route,
+			status: routeError.status
+		})
+	} : routeError;
+	if (exposeDetails) return jsonErrorResponse(routeErrorWithDiagnostics, { isRouteStateRequest: false });
+	const message = routeErrorWithDiagnostics.status >= 500 ? "Internal Server Error" : routeErrorWithDiagnostics.message;
+	return withDefaultSecurityHeaders(new Response(message, {
+		status: routeErrorWithDiagnostics.status,
+		headers: { "content-type": "text/plain; charset=utf-8" }
+	}));
+}
 async function renderRouteErrorResponse(options) {
-	const routeError = normalizeRouteError(options.error);
+	const exposeDetails = shouldExposeServerErrors(options.options);
+	const routeError = normalizeRouteError(options.error, { exposeDetails });
+	const routeErrorWithDiagnostics = exposeDetails ? {
+		...routeError,
+		diagnostics: buildRuntimeDiagnostics({
+			loaderFile: options.loaderFile,
+			middlewareFiles: options.routeArgs.route.middlewareFiles,
+			phase: options.phase,
+			route: options.routeArgs.route,
+			shellFile: options.shellFile,
+			status: routeError.status
+		})
+	} : routeError;
 	if (!options.routeModule?.ErrorBoundary) {
-		if (options.isRouteStateRequest) return withDefaultSecurityHeaders(new Response(JSON.stringify({ error: routeError }), {
-			status: routeError.status,
-			headers: { "content-type": "application/json; charset=utf-8" }
-		}));
-		const message = routeError.status >= 500 ? "Internal Server Error" : routeError.message;
+		if (options.isRouteStateRequest) return jsonErrorResponse(routeErrorWithDiagnostics, { isRouteStateRequest: true });
+		const message = routeErrorWithDiagnostics.status >= 500 ? "Internal Server Error" : routeErrorWithDiagnostics.message;
 		return withDefaultSecurityHeaders(new Response(message, {
-			status: routeError.status,
+			status: routeErrorWithDiagnostics.status,
 			headers: { "content-type": "text/plain; charset=utf-8" }
 		}));
 	}
-	if (options.isRouteStateRequest) return withDefaultSecurityHeaders(new Response(JSON.stringify({ error: routeError }), {
-		status: routeError.status,
-		headers: { "content-type": "application/json; charset=utf-8" }
-	}));
+	if (options.isRouteStateRequest) return jsonErrorResponse(routeErrorWithDiagnostics, { isRouteStateRequest: true });
 	const shellModule = options.shellModule ?? (options.shellFile ? await resolveRegistryModule(options.options.registry?.shellModules, options.shellFile) : void 0);
 	const head = shellModule?.head ? await shellModule.head(options.routeArgs) : {};
 	const cssUrls = resolvePageCssUrls(options.options, options.shellFile, options.routeArgs.route.file);
@@ -361,7 +569,7 @@ async function renderRouteErrorResponse(options) {
 	const { renderToStringAsync } = await import("preact-render-to-string");
 	const ErrorBoundary = options.routeModule.ErrorBoundary;
 	const Shell = shellModule?.Shell;
-	const errorValue = deserializeRouteError$1(routeError);
+	const errorValue = deserializeRouteError$1(routeErrorWithDiagnostics);
 	const componentTree = Shell ? h(Shell, null, h(ErrorBoundary, { error: errorValue })) : h(ErrorBoundary, { error: errorValue });
 	return htmlResponse(buildHtmlDocument({
 		head,
@@ -374,12 +582,12 @@ async function renderRouteErrorResponse(options) {
 			url: options.urlPathname,
 			routeId: options.routeId,
 			data: null,
-			error: routeError
+			error: routeErrorWithDiagnostics
 		},
 		clientEntryUrl: options.options.clientEntryUrl,
 		cssUrls,
 		modulePreloadUrls
-	}), routeError.status);
+	}), routeErrorWithDiagnostics.status);
 }
 async function runMiddlewareChain(options) {
 	let context = options.context;
@@ -409,11 +617,18 @@ async function runMiddlewareChain(options) {
 }
 async function resolveDataFunctions(route, routeModule, registry) {
 	let loader = routeModule?.loader;
+	let loaderFile = routeModule?.loader ? route.file : void 0;
 	if (route.loaderFile) {
 		const dataModule = await resolveRegistryModule(registry.dataModules, route.loaderFile);
-		if (dataModule?.loader) loader = dataModule.loader;
+		if (dataModule?.loader) {
+			loader = dataModule.loader;
+			loaderFile = route.loaderFile;
+		}
 	}
-	return { loader };
+	return {
+		loader,
+		loaderFile
+	};
 }
 async function resolveRegistryModule(modules, file) {
 	if (!modules) return void 0;
@@ -461,10 +676,10 @@ function buildHtmlDocument(options) {
 </html>`;
 }
 function htmlResponse(html, status = 200) {
-	return withDefaultSecurityHeaders(new Response(html, {
+	return withRouteResponseHeaders(new Response(html, {
 		status,
 		headers: { "content-type": "text/html; charset=utf-8" }
-	}));
+	}), { isRouteStateRequest: false });
 }
 function applyDefaultSecurityHeaders(headers) {
 	if (!headers.has("permissions-policy")) headers.set("permissions-policy", "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()");
@@ -481,6 +696,26 @@ function withDefaultSecurityHeaders(response) {
 		headers
 	});
 }
+function withRouteResponseHeaders(response, options) {
+	const headers = applyDefaultSecurityHeaders(new Headers(response.headers));
+	appendVaryHeader(headers, ROUTE_STATE_REQUEST_HEADER);
+	if (options.isRouteStateRequest && !headers.has("cache-control")) headers.set("cache-control", ROUTE_STATE_CACHE_CONTROL);
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+function appendVaryHeader(headers, value) {
+	const current = headers.get("vary");
+	if (!current) {
+		headers.set("vary", value);
+		return;
+	}
+	const values = current.split(",").map((part) => part.trim().toLowerCase()).filter(Boolean);
+	if (values.includes("*") || values.includes(value.toLowerCase())) return;
+	headers.set("vary", `${current}, ${value}`);
+}
 function escapeHtml(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -488,7 +723,7 @@ function serializeJsonForHtml(value) {
 	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
 async function prerenderApp(options) {
-	const { resolveApp } = await import("./app-CAoDWWNO.mjs").then((n) => n.t);
+	const { resolveApp } = await import("./app-Cep0el7c.mjs").then((n) => n.t);
 	const resolved = resolveApp(options.app);
 	const results = [];
 	const isgManifest = {};
@@ -530,7 +765,7 @@ async function collectSSGPaths(route, registry) {
 		console.warn(`  Warning: SSG route "${route.path}" has dynamic segments but no getStaticPaths() export, skipping.`);
 		return [];
 	}
-	const { buildPathFromSegments } = await import("./app-CAoDWWNO.mjs").then((n) => n.t);
+	const { buildPathFromSegments } = await import("./app-Cep0el7c.mjs").then((n) => n.t);
 	return (await routeModule.getStaticPaths()).map((params) => buildPathFromSegments(route.segments, params));
 }
 //#endregion
@@ -556,7 +791,7 @@ function prefetchRouteState(url) {
 	});
 	return promise;
 }
-function setupPrefetching(app) {
+function setupPrefetching(app, warmModules) {
 	let hoverTimer = null;
 	function getInternalHref(anchor) {
 		const href = anchor.getAttribute("href");
@@ -587,6 +822,10 @@ function setupPrefetching(app) {
 		if (hoverTimer) clearTimeout(hoverTimer);
 		hoverTimer = setTimeout(() => {
 			prefetchRouteState(href);
+			if (warmModules) {
+				const m = matchAppRoute(app, href);
+				if (m) warmModules(m);
+			}
 		}, 50);
 	}, true);
 	document.addEventListener("mouseleave", (e) => {
@@ -604,6 +843,10 @@ function setupPrefetching(app) {
 		const strategy = getPrefetchStrategy(href);
 		if (strategy !== "hover" && strategy !== "intent") return;
 		prefetchRouteState(href);
+		if (warmModules) {
+			const m = matchAppRoute(app, href);
+			if (m) warmModules(m);
+		}
 	}, true);
 	if (typeof IntersectionObserver === "undefined") return;
 	const observer = new IntersectionObserver((entries) => {
@@ -613,6 +856,10 @@ function setupPrefetching(app) {
 			const href = getInternalHref(anchor);
 			if (!href) continue;
 			prefetchRouteState(href);
+			if (warmModules) {
+				const m = matchAppRoute(app, href);
+				if (m) warmModules(m);
+			}
 			observer.unobserve(anchor);
 		}
 	}, { rootMargin: "200px" });
@@ -641,16 +888,34 @@ function useNavigate() {
 }
 async function initClientRouter(options) {
 	const { app, routeModules, shellModules, root, findModuleKey } = options;
-	async function buildRouteTree(match, state) {
+	const moduleCache = /* @__PURE__ */ new Map();
+	function loadModule(modules, key) {
+		let cached = moduleCache.get(key);
+		if (!cached) {
+			cached = modules[key]();
+			moduleCache.set(key, cached);
+		}
+		return cached;
+	}
+	function startRouteImport(match) {
 		const routeKey = findModuleKey(routeModules, match.route.file);
 		if (!routeKey) return null;
-		const routeMod = await routeModules[routeKey]();
+		return loadModule(routeModules, routeKey);
+	}
+	function startShellImport(match) {
+		if (!match.route.shellFile) return null;
+		const shellKey = findModuleKey(shellModules, match.route.shellFile);
+		if (!shellKey) return null;
+		return loadModule(shellModules, shellKey);
+	}
+	async function buildRouteTree(match, state, routeModPromise, shellModPromise) {
+		const routeMod = await (routeModPromise ?? startRouteImport(match));
+		if (!routeMod) return null;
 		let Shell = null;
-		if (match.route.shellFile) {
-			const shellKey = findModuleKey(shellModules, match.route.shellFile);
-			if (shellKey) Shell = (await shellModules[shellKey]()).Shell;
-		}
-		const Component = state.error ? routeMod.ErrorBoundary : routeMod.Component;
+		const resolvedShell = await (shellModPromise ?? startShellImport(match));
+		if (resolvedShell) Shell = resolvedShell.Shell;
+		const DefaultComponent = typeof routeMod.default === "function" ? routeMod.default : void 0;
+		const Component = state.error ? routeMod.ErrorBoundary : routeMod.Component ?? DefaultComponent;
 		if (!Component) return null;
 		const props = state.error ? { error: deserializeRouteError(state.error) } : {
 			data: state.data,
@@ -664,18 +929,35 @@ async function initClientRouter(options) {
 			url: match.pathname
 		}, componentTree));
 	}
+	async function buildSpaPendingTree(match, shellModPromise) {
+		const resolvedShell = await (shellModPromise ?? startShellImport(match));
+		if (!resolvedShell) return null;
+		const Shell = resolvedShell.Shell;
+		const Loading = resolvedShell.Loading;
+		const componentTree = Shell != null ? h(Shell, null, Loading ? h(Loading, null) : null) : Loading ? h(Loading, null) : null;
+		if (!componentTree) return null;
+		return h(NavigateContext.Provider, { value: navigate }, h(PrachtRuntimeProvider, {
+			data: void 0,
+			params: match.params,
+			routeId: match.route.id ?? "",
+			url: match.pathname
+		}, componentTree));
+	}
 	async function navigate(to, opts) {
 		const match = matchAppRoute(app, to);
 		if (!match) {
 			window.location.href = to;
 			return;
 		}
+		const statePromise = getCachedRouteState(to) ?? fetchPrachtRouteState(to);
+		const routeModPromise = startRouteImport(match);
+		const shellModPromise = startShellImport(match);
 		let state = {
 			data: void 0,
 			error: null
 		};
 		try {
-			const result = await (getCachedRouteState(to) ?? fetchPrachtRouteState(to));
+			const result = await statePromise;
 			if (result.type === "redirect") {
 				if (result.location) {
 					await navigate(result.location, opts);
@@ -698,7 +980,7 @@ async function initClientRouter(options) {
 		}
 		if (!opts?._popstate) if (opts?.replace) history.replaceState(null, "", to);
 		else history.pushState(null, "", to);
-		const tree = await buildRouteTree(match, state);
+		const tree = await buildRouteTree(match, state, routeModPromise, shellModPromise);
 		if (tree) {
 			render(tree, root);
 			window.scrollTo(0, 0);
@@ -715,31 +997,40 @@ async function initClientRouter(options) {
 	}
 	const initialMatch = matchAppRoute(app, options.initialState.url);
 	if (initialMatch) {
+		const initialShellPromise = initialMatch.route.render === "spa" && options.initialState.pending ? startShellImport(initialMatch) : null;
 		let state = {
 			data: options.initialState.data,
 			error: options.initialState.error ?? null
 		};
-		if (initialMatch.route.render === "spa" && state.data == null && !state.error) try {
-			const result = await fetchPrachtRouteState(options.initialState.url);
-			if (result.type === "redirect") {
-				window.location.href = result.location;
+		if (initialMatch.route.render === "spa" && options.initialState.pending) {
+			const dataPromise = fetchPrachtRouteState(options.initialState.url);
+			const pendingTree = await buildSpaPendingTree(initialMatch, initialShellPromise);
+			if (pendingTree) hydrate(pendingTree, root);
+			try {
+				const result = await dataPromise;
+				if (result.type === "redirect") {
+					window.location.href = result.location;
+					return;
+				}
+				if (result.type === "error") state = {
+					data: void 0,
+					error: result.error
+				};
+				else state = {
+					data: result.data,
+					error: null
+				};
+			} catch {
+				window.location.href = options.initialState.url;
 				return;
 			}
-			if (result.type === "error") state = {
-				data: void 0,
-				error: result.error
-			};
-			else state = {
-				data: result.data,
-				error: null
-			};
-		} catch {
-			window.location.href = options.initialState.url;
-			return;
 		}
-		const tree = await buildRouteTree(initialMatch, state);
+		const tree = await buildRouteTree(initialMatch, state, void 0, initialShellPromise);
 		if (tree) if (initialMatch.route.render === "spa") render(tree, root);
-		else hydrate(tree, root);
+		else {
+			markHydrating();
+			hydrate(tree, root);
+		}
 	}
 	document.addEventListener("click", (e) => {
 		const anchor = e.target.closest?.("a");
@@ -767,7 +1058,11 @@ async function initClientRouter(options) {
 	});
 	window.__PRACHT_NAVIGATE__ = navigate;
 	window.__PRACHT_ROUTER_READY__ = true;
-	setupPrefetching(app);
+	const warmModules = (match) => {
+		startRouteImport(match);
+		startShellImport(match);
+	};
+	setupPrefetching(app, warmModules);
 }
 const HYDRATION_BANNER_ID = "__pracht_hydration_warnings__";
 function appendHydrationWarning(message) {
@@ -821,6 +1116,7 @@ function deserializeRouteError(error) {
 	const result = new Error(error.message);
 	result.name = error.name;
 	result.status = error.status;
+	result.diagnostics = error.diagnostics;
 	return result;
 }
 //#endregion
@@ -834,4 +1130,4 @@ var PrachtHttpError = class extends Error {
 	}
 };
 //#endregion
-export { Form, PrachtHttpError, PrachtRuntimeProvider, Suspense, applyDefaultSecurityHeaders, buildPathFromSegments, defineApp, group, handlePrachtRequest, initClientRouter, lazy, matchApiRoute, matchAppRoute, prerenderApp, readHydrationState, resolveApiRoutes, resolveApp, route, startApp, timeRevalidate, useLocation, useNavigate, useParams, useRevalidate, useRevalidateRoute, useRouteData };
+export { Form, PrachtHttpError, PrachtRuntimeProvider, Suspense, applyDefaultSecurityHeaders, buildPathFromSegments, defineApp, forwardRef, group, handlePrachtRequest, initClientRouter, lazy, matchApiRoute, matchAppRoute, prerenderApp, readHydrationState, resolveApiRoutes, resolveApp, route, startApp, timeRevalidate, useIsHydrated, useLocation, useNavigate, useParams, useRevalidate, useRevalidateRoute, useRouteData };

package/package.json

@@ -1,22 +1,19 @@
 {
   "name": "@pracht/core",
-  "version": "0.0.1",
+  "version": "0.2.0",
+  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/framework",
+  "bugs": {
+    "url": "https://github.com/JoviDeCroock/pracht/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/JoviDeCroock/pracht",
     "directory": "packages/framework"
   },
-  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/framework",
-  "bugs": {
-    "url": "https://github.com/JoviDeCroock/pracht/issues"
-  },
   "files": [
     "dist"
   ],
   "type": "module",
-  "publishConfig": {
-    "provenance": true
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -27,6 +24,9 @@
       "default": "./dist/error-overlay.mjs"
     }
   },
+  "publishConfig": {
+    "provenance": true
+  },
   "dependencies": {
     "preact-suspense": "^0.2.0"
   },