@pracht/vite-plugin 0.8.0 → 0.10.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { i as scanPagesDirectory, n as generatePagesManifestSource, o as createRouteLoaderHints } from "./pages-router-BQlG21oC.mjs";
+import { c as createRouteStaticPathsHints, d as extensionGlob, f as normalizeAdditionalExtensions, i as scanPagesDirectory, l as DEFAULT_ROUTE_EXTENSIONS, n as generatePagesManifestSource, o as createRouteHeadHints, p as withAdditionalExtensions, s as createRouteLoaderHints, u as LEGACY_BARE_ROUTE_EXTENSIONS } from "./pages-router-KcCRkhnf.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import { preactSsrPrecompile } from "@pracht/preact-ssr-precompile";
 import preact from "@preact/preset-vite";
@@ -9,6 +9,7 @@ import { PRACHT_GRAPH_ONLY_ENV } from "@pracht/core/server";
 import { CAPABILITY_SETTLED_EVENT, CAPABILITY_TRANSPORT_HEADER, CONFIRMATION_HEADER } from "@pracht/capabilities";
 import { extractCapabilityProjection, extractCapabilityRegistrations, extractDefineAppObjectBody, scanTopLevelProperties } from "@pracht/capabilities/static";
 import { createNodeServerEntryModule } from "@pracht/adapter-node";
+import { Readable } from "node:stream";
 import { applyDefaultSecurityHeaders, resolveRegistryModule } from "@pracht/core";
 //#region src/client-module-query.ts
 const CLIENT_MODULE_QUERY = "pracht-client";
@@ -28,7 +29,6 @@ function stripPrachtClientModuleQuery(id) {
 function getRolldownLang(id) {
 	const path = stripPrachtClientModuleQuery(id).split("?")[0];
 	if (/\.(c|m)?tsx$/i.test(path)) return "tsx";
-	if (/\.tsrx$/i.test(path)) return "tsx";
 	if (/\.(c|m)?ts$/i.test(path)) return "ts";
 	if (/\.(c|m)?jsx$/i.test(path)) return "jsx";
 	if (/\.mdx?$/i.test(path)) return "jsx";
@@ -1258,7 +1258,15 @@ const PRACHT_CAPABILITIES_MODULE_ID = "virtual:pracht/capabilities";
 const PRACHT_WEBMCP_MODULE_ID = "virtual:pracht/webmcp";
 const CLIENT_BROWSER_PATH = "/@pracht/client.js";
 const ISLANDS_CLIENT_BROWSER_PATH = "/@pracht/islands.js";
-function readClientBuildAssets(root = process.cwd()) {
+/**
+* `base` prefixes every emitted asset URL. Vite normalizes it to leading and
+* trailing slashes; a CDN base (absolute or protocol-relative) is used as-is,
+* so the manifest paths still resolve.
+*/
+function assetUrl(file, base) {
+	return `${base}${file}`;
+}
+function readClientBuildAssets(root = process.cwd(), base = "/") {
 	const manifestPath = ["dist/client/.vite/manifest.json", "dist/.vite/manifest.json"].map((candidate) => resolve(root, candidate)).find((candidate) => existsSync(candidate));
 	if (!manifestPath) return {
 		clientEntryUrl: null,
@@ -1276,22 +1284,22 @@ function readClientBuildAssets(root = process.cwd()) {
 		if (!entry.src) continue;
 		const deps = collectTransitiveDeps(manifest, key);
 		const manifestKey = stripPrachtClientModuleQuery(entry.src);
-		if (deps.css.length > 0) cssManifest[manifestKey] = deps.css.map((f) => `/${f}`);
-		if (deps.js.length > 0) jsManifest[manifestKey] = deps.js.map((f) => `/${f}`);
+		if (deps.css.length > 0) cssManifest[manifestKey] = deps.css.map((f) => assetUrl(f, base));
+		if (deps.js.length > 0) jsManifest[manifestKey] = deps.js.map((f) => assetUrl(f, base));
 	}
-	addEntryDeps(manifest, jsManifest, PRACHT_CLIENT_MODULE_ID, clientEntry);
-	addEntryDeps(manifest, jsManifest, PRACHT_ISLANDS_CLIENT_MODULE_ID, islandsEntry);
+	addEntryDeps(manifest, jsManifest, PRACHT_CLIENT_MODULE_ID, clientEntry, base);
+	addEntryDeps(manifest, jsManifest, PRACHT_ISLANDS_CLIENT_MODULE_ID, islandsEntry, base);
 	return {
-		clientEntryUrl: clientEntry ? `/${clientEntry.file}` : null,
-		islandsEntryUrl: islandsEntry ? `/${islandsEntry.file}` : null,
+		clientEntryUrl: clientEntry ? assetUrl(clientEntry.file, base) : null,
+		islandsEntryUrl: islandsEntry ? assetUrl(islandsEntry.file, base) : null,
 		cssManifest,
 		jsManifest
 	};
 }
-function addEntryDeps(manifest, jsManifest, entryKey, entry) {
+function addEntryDeps(manifest, jsManifest, entryKey, entry, base) {
 	if (!entry) return;
 	const deps = collectTransitiveDeps(manifest, entryKey).js.filter((file) => file !== entry.file);
-	if (deps.length > 0) jsManifest[entryKey] = deps.map((file) => `/${file}`);
+	if (deps.length > 0) jsManifest[entryKey] = deps.map((file) => assetUrl(file, base));
 }
 function collectTransitiveDeps(manifest, key) {
 	const css = /* @__PURE__ */ new Set();
@@ -1343,13 +1351,16 @@ function createDefaultNodeAdapter() {
 }
 //#endregion
 //#region src/plugin-options.ts
+const CLIENT_FEATURE_DEFAULTS = { prefetch: true };
 const DEFAULTS = {
+	client: CLIENT_FEATURE_DEFAULTS,
 	appFile: "/src/routes.ts",
 	middlewareDir: "/src/middleware",
 	routesDir: "/src/routes",
 	shellsDir: "/src/shells",
 	apiDir: "/src/api",
 	serverDir: "/src/server",
+	additionalExtensions: [],
 	islandsDir: "/src/islands",
 	capabilitiesDir: "/src/capabilities",
 	adapter: createDefaultNodeAdapter(),
@@ -1368,6 +1379,8 @@ function resolveOptions(options) {
 		...options
 	};
 	if (resolved.llmsTxt === void 0) resolved.llmsTxt = false;
+	resolved.client = resolveClientOptions(options.client);
+	resolved.additionalExtensions = normalizeAdditionalExtensions(resolved.additionalExtensions);
 	if (!new Set([
 		"spa",
 		"ssr",
@@ -1380,6 +1393,20 @@ function resolveOptions(options) {
 	validateLlmsTxt(resolved.llmsTxt);
 	return resolved;
 }
+function resolveClientOptions(client) {
+	if (client === void 0) return CLIENT_FEATURE_DEFAULTS;
+	if (typeof client !== "object" || client === null) throw new Error("pracht({ client }) expects an options object.");
+	const resolved = { ...CLIENT_FEATURE_DEFAULTS };
+	for (const key of Object.keys(CLIENT_FEATURE_DEFAULTS)) {
+		const value = client[key];
+		if (value === void 0) continue;
+		if (typeof value !== "boolean") throw new Error(`pracht({ client: { ${key} } }) expects a boolean, got ${JSON.stringify(value)}.`);
+		resolved[key] = value;
+	}
+	const unknown = Object.keys(client).filter((key) => !(key in CLIENT_FEATURE_DEFAULTS));
+	if (unknown.length > 0) throw new Error(`pracht({ client }) does not accept ${unknown.map((key) => JSON.stringify(key)).join(", ")}. Known features: ${Object.keys(CLIENT_FEATURE_DEFAULTS).join(", ")}.`);
+	return resolved;
+}
 const LLMS_TXT_SECTIONS = new Set([
 	"pages",
 	"api",
@@ -1582,7 +1609,7 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"// Generated by @pracht/vite-plugin from the app manifest capability registrations.",
 		"// Contains only http-exposed capability names, endpoints, and effects —",
 		"// capability modules themselves are server-only and never reach the client graph.",
-		"import { createUseCapability } from \"@pracht/core\";",
+		"import { createUseCapability, ensureCapabilityRevalidation, withBase } from \"@pracht/core\";",
 		"",
 		`const endpoints = Object.assign(Object.create(null), JSON.parse(${JSON.stringify(JSON.stringify(endpoints))}));`,
 		"",
@@ -1598,7 +1625,7 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"    } else if (opts && opts.confirm) {",
 		`      headers.set(${JSON.stringify(CONFIRMATION_HEADER)}, opts.confirm);`,
 		"    }",
-		"    response = await fetch(endpoint.path, {",
+		"    response = await fetch(withBase(endpoint.path), {",
 		"      method: endpoint.method,",
 		"      headers,",
 		"      body: JSON.stringify(input === undefined ? {} : input),",
@@ -1643,6 +1670,7 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"}",
 		"",
 		"export async function callCapability(name, input, opts) {",
+		"  ensureCapabilityRevalidation();",
 		"  const endpoint = endpoints[name];",
 		"  if (!endpoint) {",
 		"    return {",
@@ -1791,15 +1819,6 @@ function hasWebmcpCapabilities(options = {}, root = process.cwd()) {
 }
 //#endregion
 //#region src/plugin-codegen.ts
-const ROUTE_MODULE_EXTENSIONS = new Set([
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".md",
-	".mdx",
-	".tsrx"
-]);
 const NON_FULL_HYDRATION_RE = /hydration\s*:\s*["'](?:islands|none)["']/;
 const FULL_HYDRATION_RE = /hydration\s*:\s*["']full["']/;
 const PAGES_NON_FULL_HYDRATION_RE = /export\s+const\s+HYDRATION\s*=\s*["'](?:islands|none)["']/;
@@ -1818,7 +1837,7 @@ function findMatching(source, start, open, close) {
 	}
 	return -1;
 }
-function scanFiles(dir, files) {
+function scanFiles(dir, files, extensions) {
 	let entries;
 	try {
 		entries = readdirSync(dir);
@@ -1833,15 +1852,15 @@ function scanFiles(dir, files) {
 		} catch {
 			continue;
 		}
-		if (stat.isDirectory()) scanFiles(abs, files);
-		else if (ROUTE_MODULE_EXTENSIONS.has(extname(entry))) files.push(abs);
+		if (stat.isDirectory()) scanFiles(abs, files, extensions);
+		else if (extensions.has(extname(entry))) files.push(abs);
 	}
 }
 function createNonFullHydrationExcludes(resolved, root = process.cwd()) {
 	const excludes = /* @__PURE__ */ new Set();
 	if (resolved.pagesDir) {
 		const files = [];
-		scanFiles(resolve(root, resolved.pagesDir.replace(/^\//, "")), files);
+		scanFiles(resolve(root, resolved.pagesDir.replace(/^\//, "")), files, withAdditionalExtensions(DEFAULT_ROUTE_EXTENSIONS, resolved.additionalExtensions));
 		for (const file of files) try {
 			if (PAGES_NON_FULL_HYDRATION_RE.test(readFileSync(file, "utf-8"))) excludes.add(`!/${toPosixPath$1(file).replace(toPosixPath$1(root).replace(/\/$/, "") + "/", "")}`);
 		} catch {}
@@ -1891,15 +1910,18 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 	const resolved = resolveOptions(options);
 	const isPagesMode = !!resolved.pagesDir;
 	const routeLoaderHints = createRouteLoaderHintsForVirtualModules(resolved, buildOptions.root);
+	const routeHeadHints = createRouteHeadHintsForVirtualModules(resolved, buildOptions.root);
+	const routeStaticPathsHints = createRouteStaticPathsHintsForVirtualModules(resolved, buildOptions.root);
 	const appImport = isPagesMode ? generatePagesAppInlineSource(resolved, buildOptions.root) : `import { app } from ${JSON.stringify(resolved.appFile)};`;
+	const bareRouteExtensions = [...withAdditionalExtensions(LEGACY_BARE_ROUTE_EXTENSIONS, resolved.additionalExtensions)];
 	const dirPrefix = isPagesMode ? resolved.pagesDir : resolved.routesDir;
 	const routeGlob = `${dirPrefix}/**/*.{ts,tsx,js,jsx,md,mdx}`;
-	const routeTsrxGlob = `${dirPrefix}/**/*.tsrx`;
+	const additionalRouteGlob = `${dirPrefix}/**/*.${extensionGlob(bareRouteExtensions)}`;
 	const routeExcludes = createNonFullHydrationExcludes(resolved, buildOptions.root);
 	const routeGlobPattern = routeExcludes.length > 0 ? [routeGlob, ...routeExcludes] : routeGlob;
-	const routeTsrxGlobPattern = routeExcludes.length > 0 ? [routeTsrxGlob, ...routeExcludes] : routeTsrxGlob;
+	const additionalRouteGlobPattern = additionalRouteGlob && routeExcludes.length > 0 ? [additionalRouteGlob, ...routeExcludes] : additionalRouteGlob;
 	const shellGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.{ts,tsx,js,jsx}` : `${resolved.shellsDir}/**/*.{ts,tsx,js,jsx,md,mdx}`;
-	const shellTsrxGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.tsrx` : `${resolved.shellsDir}/**/*.tsrx`;
+	const additionalShellGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.${extensionGlob(bareRouteExtensions)}` : `${resolved.shellsDir}/**/*.${extensionGlob(bareRouteExtensions)}`;
 	const appFilePosix = resolved.appFile.replace(/\\/g, "/").replace(/^\.\//, "");
 	const appDir = (appFilePosix.startsWith("/") ? appFilePosix : `/${appFilePosix}`).replace(/\/[^/]*$/, "") || "/";
 	return [
@@ -1907,17 +1929,19 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 		appImport,
 		"",
 		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
+		`const routeHeadHints = ${JSON.stringify(routeHeadHints)};`,
+		`const routeStaticPathsHints = ${JSON.stringify(routeStaticPathsHints)};`,
 		`const routeModules = {`,
 		`  ...import.meta.glob(${JSON.stringify(routeGlobPattern)}, { query: ${JSON.stringify(PRACHT_CLIENT_MODULE_QUERY)} }),`,
-		`  ...import.meta.glob(${JSON.stringify(routeTsrxGlobPattern)}),`,
+		`  ...import.meta.glob(${JSON.stringify(additionalRouteGlobPattern)}),`,
 		`};`,
 		`const shellModules = {`,
 		`  ...import.meta.glob(${JSON.stringify(shellGlob)}, { query: ${JSON.stringify(PRACHT_CLIENT_MODULE_QUERY)} }),`,
-		`  ...import.meta.glob(${JSON.stringify(shellTsrxGlob)}),`,
+		`  ...import.meta.glob(${JSON.stringify(additionalShellGlob)}),`,
 		`};`,
 		"",
 		"const resolvedApp = resolveApp(app);",
-		"applyRouteLoaderHints(resolvedApp, routeLoaderHints);",
+		"applyRouteHints(resolvedApp, routeLoaderHints, routeHeadHints, routeStaticPathsHints);",
 		"",
 		...createApplyRouteLoaderHintsSource(),
 		`const APP_DIR = ${JSON.stringify(appDir)};`,
@@ -2013,7 +2037,9 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 	const isPagesMode = !!resolved.pagesDir;
 	const registrySource = createPrachtRegistryModuleSource(resolved);
 	const routeLoaderHints = createRouteLoaderHintsForVirtualModules(resolved, buildOptions.root);
-	const clientBuild = buildOptions.isBuild ? readClientBuildAssets(buildOptions.root) : {
+	const routeHeadHints = createRouteHeadHintsForVirtualModules(resolved, buildOptions.root);
+	const routeStaticPathsHints = createRouteStaticPathsHintsForVirtualModules(resolved, buildOptions.root);
+	const clientBuild = buildOptions.isBuild ? readClientBuildAssets(buildOptions.root, buildOptions.base ?? "/") : {
 		clientEntryUrl: null,
 		islandsEntryUrl: null,
 		cssManifest: {},
@@ -2025,7 +2051,10 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 	let prachtImports = adapter?.serverImports ? adapter.serverImports + "\nimport { prerenderApp } from \"@pracht/core/server\";" : "import { resolveApp, resolveApiRoutes, prerenderApp } from \"@pracht/core/server\";";
 	if (llmsTxtConfig) prachtImports += "\nimport { buildLlmsTxt } from \"@pracht/core/server\";";
 	const appImport = isPagesMode ? generatePagesAppInlineSource(resolved, buildOptions.root) : `import { app } from ${JSON.stringify(resolved.appFile)};`;
-	const islandsEntryUrl = buildOptions.isBuild ? clientBuild.islandsEntryUrl : ISLANDS_CLIENT_BROWSER_PATH;
+	const devBase = buildOptions.base ?? "/";
+	const withDevBase = (path) => devBase === "/" ? path : `${devBase}${path.slice(1)}`;
+	const clientEntryUrl = buildOptions.isBuild ? clientBuild.clientEntryUrl : withDevBase(CLIENT_BROWSER_PATH);
+	const islandsEntryUrl = buildOptions.isBuild ? clientBuild.islandsEntryUrl : withDevBase(ISLANDS_CLIENT_BROWSER_PATH);
 	const islandsGlob = `${resolved.islandsDir}/**/*.{ts,tsx,js,jsx}`;
 	const source = [
 		prachtImports,
@@ -2033,6 +2062,8 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 		appImport,
 		"",
 		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
+		`const routeHeadHints = ${JSON.stringify(routeHeadHints)};`,
+		`const routeStaticPathsHints = ${JSON.stringify(routeStaticPathsHints)};`,
 		...createApplyRouteLoaderHintsSource(),
 		registrySource,
 		"",
@@ -2044,10 +2075,13 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 		"export const islandFiles = Object.keys(islandModules);",
 		"",
 		"export const resolvedApp = resolveApp(app);",
-		"applyRouteLoaderHints(resolvedApp, routeLoaderHints);",
+		"applyRouteHints(resolvedApp, routeLoaderHints, routeHeadHints, routeStaticPathsHints);",
 		`export const apiRoutes = resolveApiRoutes(Object.keys(apiModules), ${JSON.stringify(resolved.apiDir)});`,
 		`export const buildTarget = ${JSON.stringify(adapter?.id ?? "node")};`,
-		`export const clientEntryUrl = ${JSON.stringify(clientBuild.clientEntryUrl ?? "/@pracht/client.js")};`,
+		`export const staticTarget = ${JSON.stringify(adapter?.staticTarget === true)};`,
+		`export const buildBase = ${JSON.stringify(buildOptions.base ?? "/")};`,
+		`export const configuredBase = ${JSON.stringify(buildOptions.configuredBase)};`,
+		`export const clientEntryUrl = ${JSON.stringify(clientEntryUrl ?? "/@pracht/client.js")};`,
 		`export const islandsEntryUrl = ${JSON.stringify(islandsEntryUrl ?? null)};`,
 		`export const islandsBootstrapRequired = ${JSON.stringify(islandsBootstrapRequired)};`,
 		`export const cssManifest = ${JSON.stringify(clientBuild.cssManifest)};`,
@@ -2075,15 +2109,25 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 */
 function createPrachtDevModuleSource(options = {}, buildOptions = {}) {
 	const resolved = resolveOptions(options);
+	const routeLoaderHints = createRouteLoaderHintsForVirtualModules(resolved, buildOptions.root);
+	const routeHeadHints = createRouteHeadHintsForVirtualModules(resolved, buildOptions.root);
+	const routeStaticPathsHints = createRouteStaticPathsHintsForVirtualModules(resolved, buildOptions.root);
 	return [
 		"import { resolveApp, resolveApiRoutes } from \"@pracht/core/server\";",
 		resolved.pagesDir ? generatePagesAppInlineSource(resolved, buildOptions.root) : `import { app } from ${JSON.stringify(resolved.appFile)};`,
 		"",
+		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
+		`const routeHeadHints = ${JSON.stringify(routeHeadHints)};`,
+		`const routeStaticPathsHints = ${JSON.stringify(routeStaticPathsHints)};`,
+		...createApplyRouteLoaderHintsSource(),
 		createPrachtRegistryModuleSource(resolved),
 		"",
 		"export const resolvedApp = resolveApp(app);",
+		"applyRouteHints(resolvedApp, routeLoaderHints, routeHeadHints, routeStaticPathsHints);",
 		`export const apiRoutes = resolveApiRoutes(Object.keys(apiModules), ${JSON.stringify(resolved.apiDir)});`,
 		`export const buildTarget = ${JSON.stringify(resolved.adapter?.id ?? "node")};`,
+		`export const staticTarget = ${JSON.stringify(resolved.adapter?.staticTarget === true)};`,
+		`export const buildBase = ${JSON.stringify(buildOptions.base ?? "/")};`,
 		""
 	].join("\n");
 }
@@ -2108,7 +2152,7 @@ function resolveLlmsTxtConfig(resolved, root = process.cwd()) {
 }
 function createApplyRouteLoaderHintsSource() {
 	return [
-		"function applyRouteLoaderHints(resolvedApp, routeLoaderHints) {",
+		"function applyRouteHints(resolvedApp, routeLoaderHints, routeHeadHints, routeStaticPathsHints) {",
 		"  for (const route of resolvedApp.routes) {",
 		"    const hint = routeLoaderHints[route.file];",
 		"    if (hint === true) {",
@@ -2116,14 +2160,52 @@ function createApplyRouteLoaderHintsSource() {
 		"    } else if (typeof route.hasLoader === 'undefined' && typeof hint === 'boolean') {",
 		"      route.hasLoader = hint;",
 		"    }",
+		"    const routeHeadHint = routeHeadHints[route.file];",
+		"    const shellHeadHint = route.shellFile ? routeHeadHints[route.shellFile] : undefined;",
+		"    const hasCompleteHeadHints = typeof routeHeadHint === 'boolean' &&",
+		"      (!route.shellFile || typeof shellHeadHint === 'boolean');",
+		"    if (routeHeadHint === true || shellHeadHint === true) {",
+		"      route.hasHead = true;",
+		"    } else if (typeof route.hasHead === 'undefined' && hasCompleteHeadHints) {",
+		"      route.hasHead = routeHeadHint === true || shellHeadHint === true;",
+		"    }",
+		"    // Only ever narrows to false, and only when the scan actually saw the",
+		"    // module: an unknown route file keeps today's conservative behavior.",
+		"    const staticPathsHint = routeStaticPathsHints[route.file];",
+		"    if (typeof route.hasStaticPaths === 'undefined' && typeof staticPathsHint === 'boolean') {",
+		"      route.hasStaticPaths = staticPathsHint;",
+		"    }",
 		"  }",
 		"}",
 		""
 	];
 }
+function createRouteHeadHintsForVirtualModules(options, root = process.cwd()) {
+	const appFileDir = dirname(resolve(root, options.appFile.slice(1)));
+	const directories = options.pagesDir ? [[options.pagesDir, resolve(root, options.pagesDir.slice(1))]] : [[options.routesDir, resolve(root, options.routesDir.slice(1))], [options.shellsDir, resolve(root, options.shellsDir.slice(1))]];
+	return Object.assign({}, ...directories.map(([prefix, directory]) => createRouteHeadHints(directory, {
+		additionalExtensions: options.additionalExtensions,
+		appFileDir,
+		rootRelativePrefix: prefix
+	})));
+}
+/**
+* `getStaticPaths()` presence per route file. Only routes matter — a shell
+* cannot enumerate paths — so unlike the head hints this skips the shells
+* directory.
+*/
+function createRouteStaticPathsHintsForVirtualModules(options, root = process.cwd()) {
+	const appFileDir = dirname(resolve(root, options.appFile.slice(1)));
+	const routesPrefix = options.pagesDir || options.routesDir;
+	return createRouteStaticPathsHints(resolve(root, routesPrefix.slice(1)), {
+		additionalExtensions: options.additionalExtensions,
+		appFileDir,
+		rootRelativePrefix: routesPrefix
+	});
+}
 function createRouteLoaderHintsForVirtualModules(options, root = process.cwd()) {
 	if (options.pagesDir) {
-		const pages = scanPagesDirectory(resolve(root, options.pagesDir.slice(1)));
+		const pages = scanPagesDirectory(resolve(root, options.pagesDir.slice(1)), options.additionalExtensions);
 		const hints = {};
 		for (const page of pages) {
 			const key = `${options.pagesDir}/${page.relativePath.replace(/\\/g, "/")}`;
@@ -2133,6 +2215,7 @@ function createRouteLoaderHintsForVirtualModules(options, root = process.cwd())
 	}
 	const appFileDir = dirname(resolve(root, options.appFile.slice(1)));
 	return createRouteLoaderHints(resolve(root, options.routesDir.slice(1)), {
+		additionalExtensions: options.additionalExtensions,
 		appFileDir,
 		rootRelativePrefix: options.routesDir
 	});
@@ -2141,18 +2224,19 @@ function createPrachtRegistryModuleSource(options = {}) {
 	const resolved = resolveOptions(options);
 	const apiGlobs = [`${resolved.apiDir}/**/*.{ts,js,tsx,jsx}`, `!${resolved.apiDir}/**/*.d.ts`];
 	const isPagesMode = !!resolved.pagesDir;
+	const bareRouteExtensions = [...withAdditionalExtensions(LEGACY_BARE_ROUTE_EXTENSIONS, resolved.additionalExtensions)];
 	const routeGlob = isPagesMode ? `${resolved.pagesDir}/**/*.{ts,tsx,js,jsx,md,mdx}` : `${resolved.routesDir}/**/*.{ts,tsx,js,jsx,md,mdx}`;
-	const routeTsrxGlob = isPagesMode ? `${resolved.pagesDir}/**/*.tsrx` : `${resolved.routesDir}/**/*.tsrx`;
+	const additionalRouteGlob = `${isPagesMode ? resolved.pagesDir : resolved.routesDir}/**/*.${extensionGlob(bareRouteExtensions)}`;
 	const shellGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.{ts,tsx,js,jsx}` : `${resolved.shellsDir}/**/*.{ts,tsx,js,jsx,md,mdx}`;
-	const shellTsrxGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.tsrx` : `${resolved.shellsDir}/**/*.tsrx`;
+	const additionalShellGlob = isPagesMode ? `${resolved.pagesDir}/**/_app.${extensionGlob(bareRouteExtensions)}` : `${resolved.shellsDir}/**/*.${extensionGlob(bareRouteExtensions)}`;
 	return [
 		`export const routeModules = {`,
 		`  ...import.meta.glob(${JSON.stringify(routeGlob)}),`,
-		`  ...import.meta.glob(${JSON.stringify(routeTsrxGlob)}),`,
+		`  ...import.meta.glob(${JSON.stringify(additionalRouteGlob)}),`,
 		`};`,
 		`export const shellModules = {`,
 		`  ...import.meta.glob(${JSON.stringify(shellGlob)}),`,
-		`  ...import.meta.glob(${JSON.stringify(shellTsrxGlob)}),`,
+		`  ...import.meta.glob(${JSON.stringify(additionalShellGlob)}),`,
 		`};`,
 		`export const middlewareModules = import.meta.glob(${JSON.stringify(`${resolved.middlewareDir}/**/*.{ts,tsx,js,jsx}`)});`,
 		`export const apiModules = import.meta.glob(${JSON.stringify(apiGlobs)});`,
@@ -2176,13 +2260,15 @@ function clearPagesAppSourceCache() {
 function generatePagesAppInlineSource(options, root = process.cwd()) {
 	const absPagesDir = resolve(root, options.pagesDir.slice(1));
 	const cacheKey = JSON.stringify({
+		additionalExtensions: options.additionalExtensions,
 		absPagesDir,
 		pagesDefaultRender: options.pagesDefaultRender,
 		pagesDirPrefix: options.pagesDir
 	});
 	const cached = pagesAppSourceCache.get(cacheKey);
 	if (cached) return cached;
-	const source = generatePagesManifestSource(scanPagesDirectory(absPagesDir), {
+	const source = generatePagesManifestSource(scanPagesDirectory(absPagesDir, options.additionalExtensions), {
+		additionalExtensions: options.additionalExtensions,
 		pagesDir: absPagesDir,
 		pagesDefaultRender: options.pagesDefaultRender,
 		pagesDirPrefix: options.pagesDir
@@ -2197,8 +2283,46 @@ const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
 const CSS_MODULE_URL_RE = /\.(?:css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)/;
 const DEVTOOLS_JSON_PATH = "/_pracht.json";
 const LLMS_TXT_PATH = "/llms.txt";
+function isEventStreamContentType(contentType) {
+	return contentType.split(";", 1)[0]?.trim().toLowerCase() === "text/event-stream";
+}
+/**
+* Adapter-owned dev servers can route every browser request through their
+* platform runtime before Vite's transform middleware gets a chance to serve
+* Pracht's stable virtual client entries. Serve those two entries at their
+* public, base-prefixed URLs while leaving every other request to the adapter.
+*/
+function createOwnedDevEntryMiddleware(server) {
+	const base = server.config.base || "/";
+	return async (req, res, next) => {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method !== "GET" && method !== "HEAD") return next();
+		const requestUrl = new URL(req.url ?? "/", "http://localhost");
+		const pathname = base === "/" ? requestUrl.pathname : requestUrl.pathname.startsWith(base) ? `/${requestUrl.pathname.slice(base.length)}` : null;
+		if (pathname !== "/@pracht/client.js" && pathname !== "/@pracht/islands.js") return next();
+		try {
+			const result = await server.transformRequest(`${pathname}${requestUrl.search}`);
+			if (!result) return next();
+			if (result.etag && req.headers["if-none-match"] === result.etag) {
+				res.statusCode = 304;
+				res.end();
+				return;
+			}
+			res.statusCode = 200;
+			res.setHeader("content-type", "text/javascript");
+			res.setHeader("cache-control", "no-cache");
+			if (result.etag) res.setHeader("etag", result.etag);
+			for (const [name, value] of Object.entries(server.config.server.headers ?? {})) if (value !== void 0) res.setHeader(name, value);
+			res.end(method === "HEAD" ? void 0 : result.code);
+		} catch (error) {
+			next(error);
+		}
+	};
+}
 function createDevSSRMiddleware(server, options = {}) {
 	const maxBodySize = options.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
+	const devBase = server.config.base || "/";
+	const withDevBase = (path) => devBase === "/" || !path.startsWith("/") ? path : `${devBase}${path.slice(1)}`;
 	let warnedDevtoolsCollision = false;
 	let warnedLlmsTxtCollision = false;
 	if (options.llmsTxt && typeof server.config.publicDir === "string") {
@@ -2223,6 +2347,7 @@ function createDevSSRMiddleware(server, options = {}) {
 				await serveDevtools(server, res, {
 					apiRoutes: serverMod.apiRoutes ?? [],
 					app: serverMod.resolvedApp,
+					base: devBase,
 					url,
 					wantsJson: requestUrl.pathname === DEVTOOLS_JSON_PATH
 				});
@@ -2243,10 +2368,10 @@ function createDevSSRMiddleware(server, options = {}) {
 				return;
 			}
 			if (shouldBypassDevSSR(requestUrl, req, routeMatchers)) return next();
-			if (isDevNotFoundRequest(requestUrl, req, routeMatchers)) return serveDevNotFound(server, res, next, url, requestUrl.pathname, routeMatchers);
+			if (isDevNotFoundRequest(requestUrl, req, routeMatchers)) return serveDevNotFound(server, res, next, url, requestUrl.pathname, routeMatchers, devBase);
 			let webRequest;
 			try {
-				webRequest = await nodeToWebRequest(req, maxBodySize);
+				webRequest = await nodeToWebRequest(req, maxBodySize, devBase);
 			} catch (err) {
 				if (err instanceof Error && err.message === "Request body too large") {
 					res.statusCode = 413;
@@ -2261,8 +2386,8 @@ function createDevSSRMiddleware(server, options = {}) {
 				registry: serverMod.registry,
 				request: webRequest,
 				debugErrors: true,
-				clientEntryUrl: CLIENT_BROWSER_PATH,
-				islandsEntryUrl: ISLANDS_CLIENT_BROWSER_PATH,
+				clientEntryUrl: withDevBase(CLIENT_BROWSER_PATH),
+				islandsEntryUrl: withDevBase(ISLANDS_CLIENT_BROWSER_PATH),
 				islandsBootstrapRequired: serverMod.islandsBootstrapRequired === true,
 				apiRoutes: serverMod.apiRoutes,
 				timings
@@ -2270,8 +2395,27 @@ function createDevSSRMiddleware(server, options = {}) {
 			const responseContentType = response.headers.get("content-type") ?? "";
 			if (response.status === 404 && !responseContentType.includes("application/json") && !routeMatchers.app?.notFound) return next();
 			const contentType = response.headers.get("content-type") ?? "";
+			if (response.body && isEventStreamContentType(contentType)) {
+				res.statusCode = response.status;
+				response.headers.forEach((value, key) => {
+					res.setHeader(key, value);
+				});
+				const source = Readable.fromWeb(response.body);
+				if (res.destroyed || res.writableEnded) {
+					source.destroy();
+					return;
+				}
+				res.on("close", () => {
+					if (!res.writableFinished) source.destroy();
+				});
+				source.on("error", () => {
+					res.destroy();
+				});
+				source.pipe(res);
+				return;
+			}
 			let body = await response.text();
-			if (contentType.includes("text/html")) body = await server.transformIndexHtml(url, body);
+			if (contentType.includes("text/html")) body = await transformDevHtml(server, url, body, devBase);
 			res.statusCode = response.status;
 			response.headers.forEach((value, key) => {
 				res.setHeader(key, value);
@@ -2280,7 +2424,56 @@ function createDevSSRMiddleware(server, options = {}) {
 			if (serverTiming) res.setHeader("Server-Timing", serverTiming);
 			res.end(body);
 		} catch (error) {
-			await handleDevError(server, req, res, next, url, error);
+			await handleDevError(server, req, res, next, url, error, devBase);
+		}
+	};
+}
+/**
+* Vite's HTML transform adds `config.base` to root-absolute asset attributes.
+* Pracht's runtime has already added it to URLs produced by `withBase()` — the
+* client entry, route-state preloads, image endpoints, and user-authored asset
+* URLs — while Vite-owned or module-graph URLs still need the transform. Hide
+* the already-based strings while the hooks run, then restore them afterward,
+* so each producer applies the deploy base exactly once.
+*/
+async function transformDevHtml(server, url, html, base) {
+	if (base === "/") return server.transformIndexHtml(url, html);
+	const assetUrls = protectRootAbsoluteAssetAttributes(html);
+	let placeholder = "https://pracht.invalid/__PRACHT_DEV_BASE_PLACEHOLDER__/";
+	while (assetUrls.html.includes(placeholder)) placeholder += "_";
+	const protectedHtml = assetUrls.html.replaceAll(base, placeholder);
+	const transformedHtml = await server.transformIndexHtml(url, protectedHtml);
+	return assetUrls.restore(transformedHtml.replaceAll(placeholder, base));
+}
+const HTML_ASSET_URL_ATTRIBUTE_RE = /(\s(?:src|href|xlink:href|data|srcset|imagesrcset|poster|content)\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gi;
+/**
+* Runtime-rendered root-absolute asset URLs have already reached their final
+* public meaning: raw `/logo.svg` deliberately stays at the origin root,
+* while `withBase("/logo.svg")` is already under the deploy base. Vite's dev
+* HTML pass prefixes both, unlike production SSR, so hide complete attribute
+* values behind inert external URLs until that pass finishes.
+*/
+function protectRootAbsoluteAssetAttributes(html) {
+	let markerPrefix = "https://pracht.invalid/__PRACHT_DEV_ASSET_PLACEHOLDER__/";
+	while (html.includes(markerPrefix)) markerPrefix += "_";
+	const replacements = [];
+	return {
+		html: html.replace(HTML_ASSET_URL_ATTRIBUTE_RE, (match, prefix, doubleQuoted, singleQuoted, unquoted) => {
+			const value = doubleQuoted ?? singleQuoted ?? unquoted ?? "";
+			if (!(/(?:srcset)\s*=\s*$/i.test(prefix) ? /(?:^|,)\s*\/(?!\/)/.test(value) : /^\s*\/(?!\/)/.test(value))) return match;
+			const marker = `${markerPrefix}${replacements.length}`;
+			replacements.push({
+				marker,
+				value
+			});
+			if (doubleQuoted !== void 0) return `${prefix}"${marker}"`;
+			if (singleQuoted !== void 0) return `${prefix}'${marker}'`;
+			return `${prefix}${marker}`;
+		}),
+		restore(transformedHtml) {
+			let restoredHtml = transformedHtml;
+			for (const { marker, value } of replacements) restoredHtml = restoredHtml.replaceAll(marker, value);
+			return restoredHtml;
 		}
 	};
 }
@@ -2292,7 +2485,7 @@ function createDevSSRMiddleware(server, options = {}) {
 * avoid a first-paint FOUC.
 */
 async function createDevCssManifest(server, options) {
-	const route = options.matchAppRoute(options.app, options.pathname)?.route ?? options.app.notFound;
+	const route = options.pathname === null ? void 0 : options.matchAppRoute(options.app, options.pathname)?.route ?? options.app.notFound;
 	if (!route) return {};
 	const manifest = {};
 	const modules = [...route.shellFile ? [{
@@ -2341,18 +2534,19 @@ function collectDevCssUrls(entry) {
 	}
 	return [...urls];
 }
-function injectDevCssLinks(html, manifest) {
+function injectDevCssLinks(html, manifest, base = "/") {
 	if (!html.includes("</head>")) return html;
-	const tags = [...new Set(Object.values(manifest).flat())].map((url) => escapeHtmlAttribute(url)).filter((escapedUrl) => !html.includes(`href="${escapedUrl}"`)).map((escapedUrl) => `<link rel="stylesheet" href="${escapedUrl}">`);
+	const tags = [...new Set(Object.values(manifest).flat().map((url) => base === "/" || !url.startsWith("/") ? url : `${base}${url.slice(1)}`))].map((url) => escapeHtmlAttribute(url)).filter((escapedUrl) => !html.includes(`href="${escapedUrl}"`)).map((escapedUrl) => `<link rel="stylesheet" href="${escapedUrl}">`);
 	if (tags.length === 0) return html;
 	return html.replace("</head>", `    ${tags.join("\n    ")}\n  </head>`);
 }
-async function injectDevCssForPath(server, path, html) {
-	return injectDevCssLinks(html, await createDevCssManifest(server, await resolveDevCssContextForPath(server, path)));
+async function injectDevCssForPath(server, path, html, options = {}) {
+	return injectDevCssLinks(html, await createDevCssManifest(server, await resolveDevCssContextForPath(server, path, options)), server.config.base || "/");
 }
-async function resolveDevCssContextForPath(server, path) {
+async function resolveDevCssContextForPath(server, path, options = {}) {
 	const [framework, serverMod] = await Promise.all([server.ssrLoadModule("@pracht/core/server"), server.ssrLoadModule(PRACHT_DEV_MODULE_ID)]);
-	const pathname = new URL(path, "http://localhost").pathname;
+	const publicPathname = new URL(path, "http://localhost").pathname;
+	const pathname = options.basePathRetained ? framework.stripBase(publicPathname) : publicPathname;
 	return {
 		app: serverMod.resolvedApp,
 		matchAppRoute: framework.matchAppRoute,
@@ -2374,7 +2568,7 @@ function createDevCssInjectionMiddleware(server) {
 			next();
 			return;
 		}
-		const contextPromise = resolveDevCssContextForPath(server, req.url ?? "/").catch((error) => {
+		const contextPromise = resolveDevCssContextForPath(server, req.url ?? "/", { basePathRetained: true }).catch((error) => {
 			if (!warned) {
 				warned = true;
 				server.config.logger.warn(`[pracht] Could not discover development stylesheets: ${error instanceof Error ? error.message : String(error)}`);
@@ -2405,7 +2599,7 @@ function createDevCssInjectionMiddleware(server) {
 				try {
 					const context = await contextPromise;
 					const manifest = context ? await createDevCssManifest(server, context) : null;
-					originalEnd(manifest ? injectDevCssLinks(body.toString("utf-8"), manifest) : body.toString("utf-8"), done);
+					originalEnd(manifest ? injectDevCssLinks(body.toString("utf-8"), manifest, server.config.base || "/") : body.toString("utf-8"), done);
 				} catch {
 					originalEnd(body, done);
 				}
@@ -2453,13 +2647,13 @@ async function serveDevtools(server, res, options) {
 		res.end(JSON.stringify(graph, null, 2));
 		return;
 	}
-	let html = devtools.buildDevtoolsHtml(graph);
+	let html = devtools.buildDevtoolsHtml(graph, { base: options.base });
 	html = await server.transformIndexHtml(options.url, html);
 	res.statusCode = 200;
 	res.setHeader("content-type", "text/html; charset=utf-8");
 	res.end(html);
 }
-async function handleDevError(server, req, res, next, url, error) {
+async function handleDevError(server, req, res, next, url, error, base) {
 	if (error instanceof Error) server.ssrFixStacktrace(error);
 	if (req.headers["x-pracht-route-state-request"] === "1") {
 		res.statusCode = 500;
@@ -2476,7 +2670,8 @@ async function handleDevError(server, req, res, next, url, error) {
 		let html = buildErrorOverlayHtml({
 			message: error instanceof Error ? error.message : String(error),
 			stack: error instanceof Error ? error.stack : void 0,
-			root: server.config.root
+			root: server.config.root,
+			base
 		});
 		html = await server.transformIndexHtml(url, html);
 		res.statusCode = 500;
@@ -2505,11 +2700,12 @@ function isDevNotFoundRequest(requestUrl, req, options = {}) {
 	if (!accept.includes("text/html") && !accept.includes("application/xhtml+xml")) return false;
 	return !matchesResolvedRoute(url.pathname, options);
 }
-async function serveDevNotFound(server, res, next, url, pathname, options) {
+async function serveDevNotFound(server, res, next, url, pathname, options, base) {
 	try {
 		const { buildDevNotFoundHtml } = await server.ssrLoadModule("@pracht/core/dev-404");
 		let html = buildDevNotFoundHtml({
 			apiRoutes: options.apiRoutes.map((route) => ({ path: route.path })),
+			base,
 			requestedPath: pathname,
 			routes: options.app.routes.map((route) => ({
 				path: route.path,
@@ -2604,10 +2800,11 @@ const DEV_ASSET_EXTENSIONS = new Set([
 	".woff2",
 	".xml"
 ]);
-async function nodeToWebRequest(req, maxBodySize) {
+async function nodeToWebRequest(req, maxBodySize, base = "/") {
 	const protocol = "http";
 	const host = req.headers.host ?? "localhost";
-	const url = new URL(req.url ?? "/", `${protocol}://${host}`);
+	const path = req.url ?? "/";
+	const url = new URL(base === "/" || !path.startsWith("/") ? path : `${base}${path.slice(1)}`, `${protocol}://${host}`);
 	const method = req.method ?? "GET";
 	const headers = new Headers();
 	for (const [key, value] of Object.entries(req.headers)) {
@@ -2635,14 +2832,34 @@ async function nodeToWebRequest(req, maxBodySize) {
 }
 //#endregion
 //#region src/index.ts
+function reachesHeadBearingModule(modules, serverRoot, headHints) {
+	const pending = [...modules];
+	const seen = /* @__PURE__ */ new Set();
+	while (pending.length > 0) {
+		const module = pending.pop();
+		if (!module || seen.has(module)) continue;
+		seen.add(module);
+		const modulePath = module.file ?? module.id?.split("?", 1)[0];
+		if (modulePath) {
+			const normalizedPath = toPosixPath(modulePath);
+			if (headHints[normalizedPath.startsWith(serverRoot) ? normalizedPath.slice(serverRoot.length) : normalizedPath] === true) return true;
+		}
+		if (module.importers) pending.push(...module.importers);
+	}
+	return false;
+}
 function pracht(options = {}) {
 	const resolved = resolveOptions(options);
 	const isPagesMode = !!resolved.pagesDir;
 	let root = process.cwd();
 	let routeFileDirs = [];
+	let clientRouteHeadHints = {};
+	const routeFileExtensions = withAdditionalExtensions(DEFAULT_ROUTE_EXTENSIONS, resolved.additionalExtensions);
 	let capabilityModulePaths = /* @__PURE__ */ new Set();
 	if (isPagesMode && options.appFile) console.warn("[pracht] Both `pagesDir` and `appFile` are set. `pagesDir` takes precedence — `appFile` will be ignored.");
 	let isBuild = false;
+	let base = "/";
+	let configuredBase;
 	const prachtPlugin = {
 		name: "pracht",
 		enforce: "pre",
@@ -2654,13 +2871,17 @@ function pracht(options = {}) {
 			const envDir = _config.envDir ? resolve(configRoot, _config.envDir) : configRoot;
 			const publicEnvDefine = JSON.stringify(loadEnv(env.mode, envDir, PUBLIC_ENV_PREFIX));
 			const agentSurfaceDefine = env.command === "build" ? String(hasAgentSurface(resolved, configRoot)) : "true";
+			const staticTargetDefine = String(env.command === "build" && resolved.adapter.staticTarget === true);
+			const clientFeatureDefines = { __PRACHT_CLIENT_PREFETCH__: String(resolved.client.prefetch) };
 			return {
 				appType: "custom",
 				envPrefix: ["VITE_", PUBLIC_ENV_PREFIX],
 				resolve: { dedupe: PREACT_DEDUPE },
 				define: {
 					__PRACHT_PUBLIC_ENV__: publicEnvDefine,
-					__PRACHT_AGENT_SURFACE__: agentSurfaceDefine
+					__PRACHT_AGENT_SURFACE__: agentSurfaceDefine,
+					__PRACHT_STATIC_TARGET__: staticTargetDefine,
+					...clientFeatureDefines
 				},
 				...isSSRBuild ? {} : { build: { rollupOptions: {
 					...wantsIslandsEntry ? { input: [PRACHT_ISLANDS_CLIENT_MODULE_ID] } : {},
@@ -2683,12 +2904,15 @@ function pracht(options = {}) {
 						external: ["node:module"]
 					} } },
 					build: { rollupOptions: { external: [/^cloudflare:/] } }
-				} : {}
+				} : {},
+				...!isEdge && isSSRBuild || env.command === "serve" ? { ssr: { noExternal: [PRACHT_SSR_NO_EXTERNAL] } } : {}
 			};
 		},
 		configResolved(config) {
+			assertSafeRootAbsoluteDeployBase(config.base);
 			root = config.root;
 			isBuild = config.command === "build";
+			base = config.base;
 			routeFileDirs = computeRouteFileDirs(root, resolved);
 			capabilityModulePaths = new Set(resolveCapabilityModulePaths(resolved, root).map(canonicalFilePath));
 		},
@@ -2704,11 +2928,19 @@ function pracht(options = {}) {
 		},
 		load(id) {
 			if (isIslandsClientModule(id)) return createPrachtIslandsClientModuleSource(resolved, { root });
-			if (isClientModule(id)) return createPrachtClientModuleSource(resolved, { root });
-			if (isDevModule(id)) return createPrachtDevModuleSource(resolved, { root });
+			if (isClientModule(id)) {
+				clientRouteHeadHints = createRouteHeadHintsForVirtualModules(resolved, root);
+				return createPrachtClientModuleSource(resolved, { root });
+			}
+			if (isDevModule(id)) return createPrachtDevModuleSource(resolved, {
+				root,
+				base
+			});
 			if (isServerModule(id)) return createPrachtServerModuleSource(resolved, {
 				root,
-				isBuild
+				isBuild,
+				base,
+				configuredBase
 			});
 			if (isCapabilitiesModule(id)) return createPrachtCapabilitiesClientModuleSource(resolved, { root });
 			if (isWebmcpModule(id)) return createPrachtWebmcpModuleSource(resolved, { root });
@@ -2727,6 +2959,7 @@ function pracht(options = {}) {
 		configureServer(server) {
 			if (isPagesMode) watchPagesDirectory(server, resolved, root);
 			if (resolved.adapter.ownsDevServer) {
+				server.middlewares.use(createOwnedDevEntryMiddleware(server));
 				server.middlewares.use(createDevCssInjectionMiddleware(server));
 				return;
 			}
@@ -2745,14 +2978,29 @@ function pracht(options = {}) {
 				return html;
 			}
 		},
-		handleHotUpdate({ file, server }) {
+		handleHotUpdate({ file, modules = [], server }) {
 			const serverRoot = toPosixPath(server.config.root);
 			const normalizedFile = toPosixPath(file);
 			const relative = normalizedFile.startsWith(serverRoot) ? normalizedFile.slice(serverRoot.length) : normalizedFile;
+			const changesRouteHeadSource = isPagesMode ? relative.startsWith(resolved.pagesDir) : relative.startsWith(resolved.routesDir) || relative.startsWith(resolved.shellsDir);
+			const changesRouteHeadDependency = reachesHeadBearingModule(modules, serverRoot, clientRouteHeadHints);
+			let shouldReloadClientHead = changesRouteHeadDependency;
+			let clientHeadModule;
+			if (changesRouteHeadSource || changesRouteHeadDependency) clientHeadModule = server.moduleGraph.getModuleById(PRACHT_CLIENT_MODULE_ID);
+			if (changesRouteHeadSource) {
+				const previousHint = clientRouteHeadHints[relative];
+				try {
+					const nextHints = createRouteHeadHintsForVirtualModules(resolved, root);
+					shouldReloadClientHead ||= previousHint === true || nextHints[relative] === true;
+					clientRouteHeadHints = nextHints;
+				} catch {
+					shouldReloadClientHead = true;
+				}
+			} else if (changesRouteHeadDependency && clientHeadModule) server.moduleGraph.invalidateModule(clientHeadModule);
 			if (isPagesMode && relative.startsWith(resolved.pagesDir)) {
 				clearPagesAppSourceCache();
 				invalidateVirtualModules(server);
-				sendServerOnlyFullReload(server, file);
+				if (!sendServerOnlyFullReload(server, file) && shouldReloadClientHead && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
 				return;
 			}
 			if (!isPagesMode && relative === resolved.appFile) {
@@ -2772,7 +3020,7 @@ function pracht(options = {}) {
 				if (serverMod) server.moduleGraph.invalidateModule(serverMod);
 				const devMod = server.moduleGraph.getModuleById(PRACHT_DEV_MODULE_ID);
 				if (devMod) server.moduleGraph.invalidateModule(devMod);
-				if (relative.startsWith(resolved.routesDir)) {
+				if (relative.startsWith(resolved.routesDir) || relative.startsWith(resolved.shellsDir)) {
 					const clientMod = server.moduleGraph.getModuleById(PRACHT_CLIENT_MODULE_ID);
 					if (clientMod) server.moduleGraph.invalidateModule(clientMod);
 				}
@@ -2790,7 +3038,16 @@ function pracht(options = {}) {
 					if (capabilityMod) server.moduleGraph.invalidateModule(capabilityMod);
 				}
 			}
-			sendServerOnlyFullReload(server, file);
+			if (!sendServerOnlyFullReload(server, file) && shouldReloadClientHead && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
+		}
+	};
+	const configuredBasePlugin = {
+		name: "pracht:configured-base",
+		config: {
+			order: "post",
+			handler(config) {
+				configuredBase = typeof config.base === "string" ? config.base : void 0;
+			}
 		}
 	};
 	const clientModuleTransformPlugin = {
@@ -2798,7 +3055,7 @@ function pracht(options = {}) {
 		enforce: "post",
 		transform(code, id, transformOptions) {
 			if (!transformOptions?.ssr && isCapabilityModule(id, capabilityModulePaths)) throw new Error(`[pracht] Capability module ${JSON.stringify(toPosixPath(id))} was imported by client code. Capability modules are server-only — their run() implementation and its imports would be bundled for every visitor. Call the capability instead: \`callCapability\`/\`capabilities\` from "virtual:pracht/capabilities" in the browser, or \`invokeCapability\` from "@pracht/core/server" in loaders, middleware, and API routes.`);
-			if (!(isPrachtClientModuleId(id) || !transformOptions?.ssr && isRouteOrShellFile(id, routeFileDirs))) return null;
+			if (!(isPrachtClientModuleId(id) || !transformOptions?.ssr && isRouteOrShellFile(id, routeFileDirs, routeFileExtensions))) return null;
 			const transformed = stripServerOnlyExportsForClient(code, id);
 			if (transformed === code) return null;
 			return {
@@ -2812,7 +3069,7 @@ function pracht(options = {}) {
 		name: "pracht:optimize-deps-entries",
 		enforce: "post",
 		config(config) {
-			return withPrachtOptimizeDepsEntries(config, createPrachtOptimizeDepsEntries(resolved), createPrachtOptimizeDepsInclude(config.root ?? process.cwd()));
+			return withPrachtOptimizeDepsEntries(config, resolved, createPrachtOptimizeDepsInclude(config.root ?? process.cwd()));
 		}
 	};
 	const precompilePlugin = resolved.precompileSsrJsx ? preactSsrPrecompile({
@@ -2823,6 +3080,7 @@ function pracht(options = {}) {
 		...precompilePlugin ? [precompilePlugin] : [],
 		...preact(),
 		prachtPlugin,
+		configuredBasePlugin,
 		clientModuleTransformPlugin,
 		...edgeRuntimeSafetyPlugin ? [edgeRuntimeSafetyPlugin] : [],
 		createEnvSafetyPlugin(resolved.envSafety)
@@ -2832,6 +3090,26 @@ function pracht(options = {}) {
 	plugins.push(optimizeDepsEntriesPlugin);
 	return plugins;
 }
+function assertSafeRootAbsoluteDeployBase(base) {
+	if (typeof base !== "string" || !base.startsWith("/") || base.startsWith("//")) return;
+	let safe = !base.includes("?") && !base.includes("#");
+	if (safe) try {
+		const segments = base.split("/");
+		safe = segments.every((segment, index) => {
+			if (segment === "" && index !== 0 && index !== segments.length - 1) return false;
+			const decoded = decodeURIComponent(segment);
+			if (decoded === "." || decoded === "..") return false;
+			for (const character of decoded) {
+				const codePoint = character.codePointAt(0);
+				if (character === "/" || character === "\\" || codePoint === 0 || codePoint !== void 0 && (codePoint <= 31 || codePoint === 127)) return false;
+			}
+			return true;
+		});
+	} catch {
+		safe = false;
+	}
+	if (!safe) throw new Error(`[pracht] Vite \`base\` is set to ${JSON.stringify(base)}, but root-absolute deploy bases must contain safe URL segments. Repeated slashes, malformed escapes, and segments that decode to a path separator, \`.\`, \`..\`, NUL, or another control character are not allowed.`);
+}
 function isGraphOnlyMode() {
 	return process.env[PRACHT_GRAPH_ONLY_ENV] === "1";
 }
@@ -2915,6 +3193,7 @@ const PRACHT_OPTIMIZE_DEPS_INCLUDE = [
 	"@pracht/core/manifest"
 ];
 const PREACT_DEDUPE = ["preact", "preact-render-to-string"];
+const PRACHT_SSR_NO_EXTERNAL = /^@pracht\//;
 function createPrachtOptimizeDepsInclude(root) {
 	try {
 		if (!toPosixPath(createRequire(join(root, "package.json")).resolve("@pracht/core/package.json")).includes("/node_modules/")) return [];
@@ -2923,8 +3202,9 @@ function createPrachtOptimizeDepsInclude(root) {
 		return [];
 	}
 }
-function withPrachtOptimizeDepsEntries(config, prachtEntries, prachtInclude) {
-	const environments = Object.fromEntries(Object.entries(config.environments ?? {}).map(([name, environment]) => [name, { optimizeDeps: { entries: mergeOptimizeDepsEntries(environment.optimizeDeps?.entries, prachtEntries) } }]));
+function withPrachtOptimizeDepsEntries(config, resolved, prachtInclude) {
+	const prachtEntries = createPrachtOptimizeDepsEntries(resolved, config.optimizeDeps?.extensions);
+	const environments = Object.fromEntries(Object.entries(config.environments ?? {}).map(([name, environment]) => [name, { optimizeDeps: { entries: mergeOptimizeDepsEntries(environment.optimizeDeps?.entries, createPrachtOptimizeDepsEntries(resolved, environment.optimizeDeps?.extensions ?? config.optimizeDeps?.extensions)) } }]));
 	return {
 		optimizeDeps: {
 			entries: mergeOptimizeDepsEntries(config.optimizeDeps?.entries, prachtEntries),
@@ -2933,9 +3213,24 @@ function withPrachtOptimizeDepsEntries(config, prachtEntries, prachtInclude) {
 		...Object.keys(environments).length > 0 ? { environments } : {}
 	};
 }
-function createPrachtOptimizeDepsEntries(resolved) {
+const VITE_SCANNABLE_ROUTE_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mts",
+	".mjs",
+	".cts",
+	".cjs",
+	".vue",
+	".svelte",
+	".astro",
+	".imba"
+]);
+function createPrachtOptimizeDepsEntries(resolved, optimizerExtensions) {
 	const scriptExtensions = "{ts,tsx,js,jsx}";
-	const routeExtensions = "{ts,tsx,js,jsx,md,mdx,tsrx}";
+	const explicitlyScannable = new Set(optimizerExtensions ?? []);
+	const routeExtensions = extensionGlob([...new Set([...DEFAULT_ROUTE_EXTENSIONS, ...resolved.additionalExtensions])].filter((extension) => VITE_SCANNABLE_ROUTE_EXTENSIONS.has(extension) || explicitlyScannable.has(extension)));
 	const apiDir = toOptimizeDepsEntry(resolved.apiDir);
 	const apiEntries = [`${apiDir}/**/*.{ts,js,tsx,jsx}`, `!${apiDir}/**/*.d.ts`];
 	const entries = resolved.pagesDir ? [
@@ -2985,15 +3280,6 @@ function invalidateVirtualModules(server) {
 	if (serverMod) server.moduleGraph.invalidateModule(serverMod);
 	if (devMod) server.moduleGraph.invalidateModule(devMod);
 }
-const ROUTE_FILE_EXTENSIONS = new Set([
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".md",
-	".mdx",
-	".tsrx"
-]);
 function computeRouteFileDirs(root, resolved) {
 	return (resolved.pagesDir ? [resolved.pagesDir] : [resolved.routesDir, resolved.shellsDir]).map((dir) => canonicalFilePath(resolveConfigPath(root, dir))).map(withTrailingSep);
 }
@@ -3024,7 +3310,7 @@ function canonicalFilePath(path) {
 		return toPosixPath(path);
 	}
 }
-function isRouteOrShellFile(id, dirs) {
+function isRouteOrShellFile(id, dirs, extensions) {
 	if (dirs.length === 0) return false;
 	const queryStart = id.indexOf("?");
 	const path = queryStart === -1 ? id : id.slice(0, queryStart);
@@ -3032,7 +3318,7 @@ function isRouteOrShellFile(id, dirs) {
 	const extIndex = path.lastIndexOf(".");
 	if (extIndex === -1) return false;
 	const ext = path.slice(extIndex);
-	if (!ROUTE_FILE_EXTENSIONS.has(ext)) return false;
+	if (!extensions.has(ext)) return false;
 	const normalized = toPosixPath(path);
 	return dirs.some((dir) => normalized.startsWith(dir));
 }