@pracht/vite-plugin 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -5,6 +5,41 @@ import { RenderMode, RenderMode as RenderMode$1 } from "@pracht/core";
 //#region src/plugin-assets.d.ts
 declare const PRACHT_CLIENT_MODULE_ID = "virtual:pracht/client";
 declare const PRACHT_SERVER_MODULE_ID = "virtual:pracht/server";
+declare const PRACHT_ISLANDS_CLIENT_MODULE_ID = "virtual:pracht/islands-client";
+//#endregion
+//#region src/env-safety.d.ts
+/**
+ * Env vars Vite defines on `import.meta.env` in every bundle, plus NODE_ENV
+ * which Vite's define pass statically replaces at build time (so it can never
+ * leak and is referenced by countless dependencies).
+ */
+declare const VITE_BUILTIN_ENV_VARS: Set<string>;
+/** Prefix that marks an env var as intentionally public. */
+declare const PUBLIC_ENV_PREFIX = "PRACHT_PUBLIC_";
+interface EnvSafetyOptions {
+  /** Env var names allowed to appear in client bundles despite not being public. */
+  allow?: string[];
+}
+interface EnvLeakReference {
+  accessor: "process.env" | "import.meta.env";
+  name: string;
+}
+/**
+ * Scans JavaScript source for references to environment variables that are
+ * neither public-prefixed, Vite built-ins, nor explicitly allowed.
+ */
+declare function scanCodeForEnvLeaks(code: string, allow?: ReadonlySet<string>): EnvLeakReference[];
+interface EnvLeakProblem extends EnvLeakReference {
+  chunk: string;
+  sources: string[];
+}
+declare function formatEnvLeakError(problems: EnvLeakProblem[]): string;
+/**
+ * Build-time leak detection: scans rendered client chunks for references to
+ * non-public env vars and fails the build with the variable, chunk, and the
+ * likely source module.
+ */
+declare function createEnvSafetyPlugin(envSafety: false | EnvSafetyOptions): Plugin;
 //#endregion
 //#region src/plugin-adapter.d.ts
 /**
@@ -56,6 +91,11 @@ interface PrachtPluginOptions {
   middlewareDir?: string;
   apiDir?: string;
   serverDir?: string;
+  /**
+   * Directory containing island components hydrated on
+   * `hydration: "islands"` routes. Defaults to "/src/islands".
+   */
+  islandsDir?: string;
   adapter?: PrachtAdapter;
   /** Enable file-system pages routing by pointing to the pages directory (e.g. "/src/pages"). */
   pagesDir?: string;
@@ -78,12 +118,26 @@ interface PrachtPluginOptions {
    * Client bundles keep the normal Preact JSX transform for hydration.
    */
   precompileSsrJsx?: boolean | PreactSsrPrecompileOptions;
+  /**
+   * Client-bundle env leak detection. Enabled by default: production client
+   * chunks referencing `process.env.X` / `import.meta.env.X` for a non-public
+   * variable fail the build. Pass `{ allow: ["NAME"] }` to permit specific
+   * variables, or `false` to disable the check entirely.
+   */
+  envSafety?: false | EnvSafetyOptions;
 }
 //#endregion
 //#region src/plugin-codegen.d.ts
 declare function createPrachtClientModuleSource(options?: PrachtPluginOptions, buildOptions?: {
   root?: string;
 }): string;
+/**
+ * Source of `virtual:pracht/islands-client` — the tiny bootstrap loaded by
+ * `hydration: "islands"` routes. It deliberately does NOT import the app
+ * manifest, the router, or the full client runtime: it only scans the DOM
+ * for island markers and hydrates the islands present on the page.
+ */
+declare function createPrachtIslandsClientModuleSource(options?: PrachtPluginOptions): string;
 declare function createPrachtServerModuleSource(options?: PrachtPluginOptions, buildOptions?: {
   root?: string;
   isBuild?: boolean;
@@ -93,4 +147,4 @@ declare function createPrachtRegistryModuleSource(options?: PrachtPluginOptions)
 //#region src/index.d.ts
 declare function pracht(options?: PrachtPluginOptions): Plugin[];
 //#endregion
-export { PRACHT_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, type PrachtAdapter, type PrachtPluginOptions, type RenderMode, createPrachtClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, pracht };
+export { type EnvLeakReference, type EnvSafetyOptions, PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PUBLIC_ENV_PREFIX, type PrachtAdapter, type PrachtPluginOptions, type RenderMode, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, formatEnvLeakError, pracht, scanCodeForEnvLeaks };

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { i as scanPagesDirectory, n as generatePagesManifestSource, o as createRouteLoaderHints } from "./pages-router-BN3V7ii7.mjs";
+import { i as scanPagesDirectory, n as generatePagesManifestSource, o as createRouteLoaderHints } from "./pages-router-BsVlzz-e.mjs";
 import { createRequire } from "node:module";
 import { preactSsrPrecompile } from "@pracht/preact-ssr-precompile";
 import preact from "@preact/preset-vite";
-import { dirname, join, resolve } from "node:path";
+import { dirname, extname, join, resolve } from "node:path";
 import { parseAst } from "vite";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { createNodeServerEntryModule } from "@pracht/adapter-node";
 //#region src/client-module-query.ts
 const CLIENT_MODULE_QUERY = "pracht-client";
@@ -888,20 +888,323 @@ function enqueueDependencies(target, dependencies) {
 	for (const name of dependencies) target.add(name);
 }
 //#endregion
+//#region src/env-safety.ts
+/**
+* Env vars Vite defines on `import.meta.env` in every bundle, plus NODE_ENV
+* which Vite's define pass statically replaces at build time (so it can never
+* leak and is referenced by countless dependencies).
+*/
+const VITE_BUILTIN_ENV_VARS = new Set([
+	"MODE",
+	"DEV",
+	"PROD",
+	"SSR",
+	"BASE_URL",
+	"NODE_ENV"
+]);
+/** Prefix that marks an env var as intentionally public. */
+const PUBLIC_ENV_PREFIX = "PRACHT_PUBLIC_";
+/** Server-only core entry that must never resolve into client bundles. */
+const SERVER_ENV_MODULE_ID = "@pracht/core/env/server";
+const ENV_REFERENCE_RE = /\b(process\.env|import\.meta\.env)(?:\.([A-Za-z_$][A-Za-z0-9_$]*)|\[\s*(["'])([A-Za-z_$][A-Za-z0-9_$]*)\3\s*\])/g;
+/**
+* Scans JavaScript source for references to environment variables that are
+* neither public-prefixed, Vite built-ins, nor explicitly allowed.
+*/
+function scanCodeForEnvLeaks(code, allow = /* @__PURE__ */ new Set()) {
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	const codePositions = getCodePositionMask(code);
+	for (const match of code.matchAll(ENV_REFERENCE_RE)) {
+		if (!codePositions[match.index ?? -1]) continue;
+		const accessor = match[1];
+		const name = match[2] ?? match[4];
+		if (!name) continue;
+		if (name.startsWith("PRACHT_PUBLIC_")) continue;
+		if (VITE_BUILTIN_ENV_VARS.has(name)) continue;
+		if (allow.has(name)) continue;
+		const key = `${accessor}.${name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		findings.push({
+			accessor,
+			name
+		});
+	}
+	return findings;
+}
+function getCodePositionMask(code) {
+	const mask = new Uint8Array(code.length);
+	const templateExpressionDepths = [];
+	let mode = "code";
+	let regexCharClass = false;
+	let i = 0;
+	while (i < code.length) {
+		const char = code[i];
+		const next = code[i + 1];
+		if (mode === "line-comment") {
+			if (char === "\n" || char === "\r") {
+				mode = "code";
+				mask[i] = 1;
+			}
+			i++;
+			continue;
+		}
+		if (mode === "block-comment") {
+			if (char === "*" && next === "/") {
+				mode = "code";
+				i += 2;
+			} else i++;
+			continue;
+		}
+		if (mode === "single" || mode === "double") {
+			const quote = mode === "single" ? "'" : "\"";
+			if (char === "\\") {
+				i += 2;
+				continue;
+			}
+			if (char === quote || char === "\n" || char === "\r") mode = "code";
+			i++;
+			continue;
+		}
+		if (mode === "regex") {
+			if (char === "\\") {
+				i += 2;
+				continue;
+			}
+			if (char === "[") {
+				regexCharClass = true;
+				i++;
+				continue;
+			}
+			if (char === "]") {
+				regexCharClass = false;
+				i++;
+				continue;
+			}
+			if (char === "/" && !regexCharClass) {
+				regexCharClass = false;
+				i++;
+				while (i < code.length && isIdentifierChar(code[i])) i++;
+				mode = "code";
+				continue;
+			}
+			if (char === "\n" || char === "\r") {
+				regexCharClass = false;
+				mode = "code";
+			}
+			i++;
+			continue;
+		}
+		if (mode === "template") {
+			if (char === "\\") {
+				i += 2;
+				continue;
+			}
+			if (char === "`") {
+				mode = "code";
+				i++;
+				continue;
+			}
+			if (char === "$" && next === "{") {
+				mask[i] = 1;
+				mask[i + 1] = 1;
+				templateExpressionDepths.push(1);
+				mode = "code";
+				i += 2;
+				continue;
+			}
+			i++;
+			continue;
+		}
+		mask[i] = 1;
+		if (char === "/" && next === "/") {
+			mask[i + 1] = 1;
+			mode = "line-comment";
+			i += 2;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			mask[i + 1] = 1;
+			mode = "block-comment";
+			i += 2;
+			continue;
+		}
+		if (char === "/" && isRegexLiteralStart(code, i)) {
+			mode = "regex";
+			regexCharClass = false;
+			i++;
+			continue;
+		}
+		if (char === "'") {
+			mode = "single";
+			i++;
+			continue;
+		}
+		if (char === "\"") {
+			mode = "double";
+			i++;
+			continue;
+		}
+		if (char === "`") {
+			mode = "template";
+			i++;
+			continue;
+		}
+		if (templateExpressionDepths.length > 0) {
+			const top = templateExpressionDepths.length - 1;
+			if (char === "{") templateExpressionDepths[top]++;
+			else if (char === "}") {
+				templateExpressionDepths[top]--;
+				if (templateExpressionDepths[top] === 0) {
+					templateExpressionDepths.pop();
+					mode = "template";
+				}
+			}
+		}
+		i++;
+	}
+	return mask;
+}
+function isRegexLiteralStart(code, slashIndex) {
+	let i = slashIndex - 1;
+	while (i >= 0 && /\s/.test(code[i])) i--;
+	if (i < 0) return true;
+	const previous = code[i];
+	if (previous === ">" && code[i - 1] === "=") return true;
+	if ("([{=,:;!?&|^~<>*%+-".includes(previous)) return true;
+	if (isIdentifierChar(previous)) {
+		let start = i;
+		while (start >= 0 && isIdentifierChar(code[start])) start--;
+		const word = code.slice(start + 1, i + 1);
+		return new Set([
+			"await",
+			"case",
+			"delete",
+			"do",
+			"else",
+			"in",
+			"instanceof",
+			"new",
+			"of",
+			"return",
+			"throw",
+			"typeof",
+			"void",
+			"yield"
+		]).has(word);
+	}
+	return false;
+}
+function isIdentifierChar(char) {
+	return !!char && /[A-Za-z0-9_$]/.test(char);
+}
+function formatEnvLeakError(problems) {
+	return [
+		"[pracht] Environment variable leak detected in the client bundle:",
+		...problems.map((problem) => {
+			const source = problem.sources.length > 0 ? ` (likely from ${problem.sources.map((file) => JSON.stringify(file)).join(", ")})` : "";
+			return `  - ${problem.accessor}.${problem.name} in chunk "${problem.chunk}"${source}`;
+		}),
+		"",
+		`Only PRACHT_PUBLIC_-prefixed variables may be referenced in client code (prefer publicEnv from "@pracht/core" for typed public values).`,
+		`Move server-only reads into loaders/API routes and access them via serverEnv from "@pracht/core/env/server",`,
+		"or allowlist intentionally-safe names with pracht({ envSafety: { allow: [...] } })."
+	].join("\n");
+}
+function stripIdQuery(id) {
+	const queryStart = id.indexOf("?");
+	return queryStart === -1 ? id : id.slice(0, queryStart);
+}
+/**
+* Build-time leak detection: scans rendered client chunks for references to
+* non-public env vars and fails the build with the variable, chunk, and the
+* likely source module.
+*/
+function createEnvSafetyPlugin(envSafety) {
+	const allow = new Set(envSafety === false ? [] : envSafety.allow ?? []);
+	const moduleEnvReferences = /* @__PURE__ */ new Map();
+	let isSsrBuild = false;
+	return {
+		name: "pracht:env-safety",
+		apply: "build",
+		enforce: "post",
+		configResolved(config) {
+			isSsrBuild = !!config.build.ssr;
+		},
+		transform(code, id, transformOptions) {
+			if (envSafety === false) return null;
+			if (transformOptions?.ssr) return null;
+			const moduleId = stripIdQuery(id);
+			if (moduleId.includes("node_modules")) return null;
+			const findings = scanCodeForEnvLeaks(code, allow);
+			if (findings.length > 0) moduleEnvReferences.set(moduleId, findings);
+			return null;
+		},
+		generateBundle(_options, bundle) {
+			if (envSafety === false) return;
+			const consumer = this.environment?.config?.consumer;
+			if (!(consumer ? consumer === "client" : !isSsrBuild)) return;
+			const problems = [];
+			const seen = /* @__PURE__ */ new Set();
+			const addProblem = (problem) => {
+				const key = `${problem.chunk}:${problem.accessor}.${problem.name}`;
+				if (seen.has(key)) return;
+				seen.add(key);
+				problems.push(problem);
+			};
+			for (const [fileName, output] of Object.entries(bundle)) {
+				if (output.type !== "chunk") continue;
+				const moduleIds = (output.moduleIds ?? Object.keys(output.modules ?? {})).map(stripIdQuery);
+				for (const moduleId of moduleIds) {
+					const references = moduleEnvReferences.get(moduleId);
+					if (!references) continue;
+					for (const reference of references) addProblem({
+						...reference,
+						chunk: fileName,
+						sources: [moduleId]
+					});
+				}
+				for (const finding of scanCodeForEnvLeaks(output.code, allow)) {
+					const sources = moduleIds.filter((moduleId) => moduleEnvReferences.get(moduleId)?.some((reference) => reference.name === finding.name));
+					addProblem({
+						...finding,
+						chunk: fileName,
+						sources
+					});
+				}
+			}
+			if (problems.length > 0) this.error(formatEnvLeakError(problems));
+			this.emitFile({
+				fileName: "_pracht/env-safety.json",
+				source: JSON.stringify({
+					findings: problems,
+					version: 1
+				}, null, 2),
+				type: "asset"
+			});
+		}
+	};
+}
+//#endregion
 //#region src/plugin-assets.ts
 const PRACHT_CLIENT_MODULE_ID = "virtual:pracht/client";
 const PRACHT_SERVER_MODULE_ID = "virtual:pracht/server";
+const PRACHT_ISLANDS_CLIENT_MODULE_ID = "virtual:pracht/islands-client";
 const CLIENT_BROWSER_PATH = "/@pracht/client.js";
+const ISLANDS_CLIENT_BROWSER_PATH = "/@pracht/islands.js";
 function readClientBuildAssets(root = process.cwd()) {
 	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,
+		islandsEntryUrl: null,
 		cssManifest: {},
 		jsManifest: {}
 	};
 	const rawManifest = readFileSync(manifestPath, "utf-8");
 	const manifest = JSON.parse(rawManifest);
 	const clientEntry = manifest[PRACHT_CLIENT_MODULE_ID];
+	const islandsEntry = manifest[PRACHT_ISLANDS_CLIENT_MODULE_ID];
 	const cssManifest = {};
 	const jsManifest = {};
 	for (const [key, entry] of Object.entries(manifest)) {
@@ -911,12 +1214,20 @@ function readClientBuildAssets(root = process.cwd()) {
 		if (deps.css.length > 0) cssManifest[manifestKey] = deps.css.map((f) => `/${f}`);
 		if (deps.js.length > 0) jsManifest[manifestKey] = deps.js.map((f) => `/${f}`);
 	}
+	addEntryDeps(manifest, jsManifest, PRACHT_CLIENT_MODULE_ID, clientEntry);
+	addEntryDeps(manifest, jsManifest, PRACHT_ISLANDS_CLIENT_MODULE_ID, islandsEntry);
 	return {
 		clientEntryUrl: clientEntry ? `/${clientEntry.file}` : null,
+		islandsEntryUrl: islandsEntry ? `/${islandsEntry.file}` : null,
 		cssManifest,
 		jsManifest
 	};
 }
+function addEntryDeps(manifest, jsManifest, entryKey, entry) {
+	if (!entry) return;
+	const deps = collectTransitiveDeps(manifest, entryKey).js.filter((file) => file !== entry.file);
+	if (deps.length > 0) jsManifest[entryKey] = deps.map((file) => `/${file}`);
+}
 function collectTransitiveDeps(manifest, key) {
 	const css = /* @__PURE__ */ new Set();
 	const js = /* @__PURE__ */ new Set();
@@ -942,6 +1253,9 @@ function isClientModule(id) {
 function isServerModule(id) {
 	return id === "virtual:pracht/server" || id.endsWith("virtual:pracht/server");
 }
+function isIslandsClientModule(id) {
+	return id === "virtual:pracht/islands-client" || id === "/@pracht/islands.js" || id.endsWith("virtual:pracht/islands-client");
+}
 //#endregion
 //#region src/plugin-adapter.ts
 function createDefaultNodeAdapter() {
@@ -962,13 +1276,15 @@ const DEFAULTS = {
 	shellsDir: "/src/shells",
 	apiDir: "/src/api",
 	serverDir: "/src/server",
+	islandsDir: "/src/islands",
 	adapter: createDefaultNodeAdapter(),
 	pagesDir: "",
 	pagesDefaultRender: "ssr",
 	prerenderConcurrency: 10,
 	maxBodySize: 1024 * 1024,
 	budgets: {},
-	precompileSsrJsx: false
+	precompileSsrJsx: false,
+	envSafety: {}
 };
 function resolveOptions(options) {
 	const resolved = {
@@ -990,6 +1306,102 @@ function validateBudgets(budgets) {
 }
 //#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)["']/;
+function toPosixPath$1(path) {
+	return path.replace(/\\/g, "/");
+}
+function findMatching(source, start, open, close) {
+	let depth = 0;
+	for (let i = start; i < source.length; i++) {
+		const ch = source[i];
+		if (ch === open) depth++;
+		if (ch === close) {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+function scanFiles(dir, files) {
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const abs = join(dir, entry);
+		let stat;
+		try {
+			stat = statSync(abs);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) scanFiles(abs, files);
+		else if (ROUTE_MODULE_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);
+		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 {}
+		return [...excludes];
+	}
+	const appFile = resolve(root, resolved.appFile.replace(/^\//, ""));
+	let source;
+	try {
+		source = readFileSync(appFile, "utf-8");
+	} catch {
+		return [];
+	}
+	const groups = [];
+	for (const match of source.matchAll(/\bgroup\s*\(/g)) {
+		const parenStart = match.index + match[0].lastIndexOf("(");
+		const parenEnd = findMatching(source, parenStart, "(", ")");
+		if (parenEnd === -1) continue;
+		const args = source.slice(parenStart + 1, parenEnd);
+		const arrayStart = source.indexOf("[", parenStart);
+		if (arrayStart === -1 || arrayStart > parenEnd) continue;
+		const arrayEnd = findMatching(source, arrayStart, "[", "]");
+		if (arrayEnd === -1) continue;
+		groups.push({
+			start: arrayStart,
+			end: arrayEnd,
+			nonFull: NON_FULL_HYDRATION_RE.test(args.split("[")[0] ?? "")
+		});
+	}
+	const appDir = dirname(appFile);
+	for (const match of source.matchAll(/\broute\s*\(\s*[^,]+,\s*(?:(?:\(\s*\)\s*=>\s*import\s*\(\s*)?["']([^"']+)["']\s*\)?|["']([^"']+)["'])/g)) {
+		const fileRef = match[1] ?? match[2];
+		const callStart = match.index;
+		const parenStart = source.indexOf("(", callStart);
+		const parenEnd = findMatching(source, parenStart, "(", ")");
+		if (parenEnd === -1) continue;
+		const callSource = source.slice(parenStart, parenEnd);
+		const ownNonFull = NON_FULL_HYDRATION_RE.test(callSource);
+		const ownFull = FULL_HYDRATION_RE.test(callSource);
+		const inheritedNonFull = groups.filter((group) => group.start < callStart && callStart < group.end).sort((a, b) => b.start - a.start)[0]?.nonFull;
+		if (ownFull || !ownNonFull && inheritedNonFull !== true) continue;
+		const abs = resolve(appDir, fileRef);
+		excludes.add(`!/${toPosixPath$1(abs).replace(toPosixPath$1(root).replace(/\/$/, "") + "/", "")}`);
+	}
+	return [...excludes];
+}
 function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 	const resolved = resolveOptions(options);
 	const isPagesMode = !!resolved.pagesDir;
@@ -998,16 +1410,21 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 	const dirPrefix = isPagesMode ? resolved.pagesDir : resolved.routesDir;
 	const routeGlob = `${dirPrefix}/**/*.{ts,tsx,js,jsx,md,mdx}`;
 	const routeTsrxGlob = `${dirPrefix}/**/*.tsrx`;
+	const routeExcludes = createNonFullHydrationExcludes(resolved, buildOptions.root);
+	const routeGlobPattern = routeExcludes.length > 0 ? [routeGlob, ...routeExcludes] : routeGlob;
+	const routeTsrxGlobPattern = routeExcludes.length > 0 ? [routeTsrxGlob, ...routeExcludes] : routeTsrxGlob;
 	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 appFilePosix = resolved.appFile.replace(/\\/g, "/").replace(/^\.\//, "");
+	const appDir = (appFilePosix.startsWith("/") ? appFilePosix : `/${appFilePosix}`).replace(/\/[^/]*$/, "") || "/";
 	return [
 		"import { resolveApp, initClientRouter, readHydrationState } from \"@pracht/core/client\";",
 		appImport,
 		"",
 		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
 		`const routeModules = {`,
-		`  ...import.meta.glob(${JSON.stringify(routeGlob)}, { query: ${JSON.stringify(PRACHT_CLIENT_MODULE_QUERY)} }),`,
-		`  ...import.meta.glob(${JSON.stringify(routeTsrxGlob)}),`,
+		`  ...import.meta.glob(${JSON.stringify(routeGlobPattern)}, { query: ${JSON.stringify(PRACHT_CLIENT_MODULE_QUERY)} }),`,
+		`  ...import.meta.glob(${JSON.stringify(routeTsrxGlobPattern)}),`,
 		`};`,
 		`const shellModules = {`,
 		`  ...import.meta.glob(${JSON.stringify(shellGlob)}, { query: ${JSON.stringify(PRACHT_CLIENT_MODULE_QUERY)} }),`,
@@ -1018,8 +1435,22 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 		"applyRouteLoaderHints(resolvedApp, routeLoaderHints);",
 		"",
 		...createApplyRouteLoaderHintsSource(),
-		"function normalizeModuleKey(key) {",
-		"  return key.split(\"?\")[0].replace(/^\\.?\\//, \"\");",
+		`const APP_DIR = ${JSON.stringify(appDir)};`,
+		"",
+		"// Manifest refs are written relative to the app manifest file",
+		"// (\"./routes/home.tsx\") while import.meta.glob keys are root-absolute",
+		"// (\"/src/routes/home.tsx\"). Both sides canonicalize against APP_DIR —",
+		"// known at build time — replacing the previous runtime suffix index.",
+		"function canonicalModuleKey(path) {",
+		"  const raw = path.split(\"?\")[0];",
+		"  const joined = raw.startsWith(\"/\") ? raw : APP_DIR + \"/\" + raw;",
+		"  const parts = [];",
+		"  for (const segment of joined.split(\"/\")) {",
+		"    if (!segment || segment === \".\") continue;",
+		"    if (segment === \"..\") parts.pop();",
+		"    else parts.push(segment);",
+		"  }",
+		"  return \"/\" + parts.join(\"/\");",
 		"}",
 		"",
 		"const moduleKeyIndexes = new WeakMap();",
@@ -1027,22 +1458,34 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 		"  let index = moduleKeyIndexes.get(modules);",
 		"  if (index) return index;",
 		"  index = new Map();",
-		"  for (const key of Object.keys(modules)) {",
-		"    const normalized = normalizeModuleKey(key);",
-		"    if (!normalized) continue;",
-		"    if (!index.has(normalized)) index.set(normalized, key);",
-		"    for (let i = normalized.indexOf(\"/\"); i !== -1; i = normalized.indexOf(\"/\", i + 1)) {",
-		"      const suffix = normalized.slice(i + 1);",
-		"      if (suffix && !index.has(suffix)) index.set(suffix, key);",
-		"    }",
-		"  }",
+		"  for (const key of Object.keys(modules)) index.set(canonicalModuleKey(key), key);",
 		"  moduleKeyIndexes.set(modules, index);",
 		"  return index;",
 		"}",
 		"",
 		"function findModuleKey(modules, file) {",
 		"  if (file in modules) return file;",
-		"  return getModuleKeyIndex(modules).get(normalizeModuleKey(file)) ?? null;",
+		"  const key = getModuleKeyIndex(modules).get(canonicalModuleKey(file));",
+		"  if (key != null) return key;",
+		"  if (import.meta.env?.DEV) {",
+		"    // Dev-only lenient fallback so refs that never canonicalize (written",
+		"    // relative to a file other than the app manifest) keep working while",
+		"    // the console error tells the author to fix them — production builds",
+		"    // resolve strictly and drop this branch.",
+		"    const suffix = \"/\" + file.split(\"?\")[0].replace(/^\\.?\\//, \"\");",
+		"    for (const candidate of Object.keys(modules)) {",
+		"      if (canonicalModuleKey(candidate).endsWith(suffix)) {",
+		"        console.error(",
+		"          `[pracht] Module ref ${JSON.stringify(file)} only resolved by suffix matching ` +",
+		"            `against ${JSON.stringify(candidate)}. Write manifest refs relative to the app ` +",
+		"            `manifest file (e.g. \"./routes/home.tsx\") — suffix matching is disabled in ` +",
+		"            `production builds.`,",
+		"        );",
+		"        return candidate;",
+		"      }",
+		"    }",
+		"  }",
+		"  return null;",
 		"}",
 		"",
 		"const state = readHydrationState();",
@@ -1060,6 +1503,23 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 		""
 	].join("\n");
 }
+/**
+* Source of `virtual:pracht/islands-client` — the tiny bootstrap loaded by
+* `hydration: "islands"` routes. It deliberately does NOT import the app
+* manifest, the router, or the full client runtime: it only scans the DOM
+* for island markers and hydrates the islands present on the page.
+*/
+function createPrachtIslandsClientModuleSource(options = {}) {
+	const islandsGlob = `${resolveOptions(options).islandsDir}/**/*.{ts,tsx,js,jsx}`;
+	return [
+		"import { hydrateIslands } from \"@pracht/core/islands-client\";",
+		"",
+		`const islandModules = import.meta.glob(${JSON.stringify(islandsGlob)});`,
+		"",
+		"hydrateIslands({ modules: islandModules });",
+		""
+	].join("\n");
+}
 function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 	const resolved = resolveOptions(options);
 	const isPagesMode = !!resolved.pagesDir;
@@ -1067,23 +1527,37 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 	const routeLoaderHints = createRouteLoaderHintsForVirtualModules(resolved, buildOptions.root);
 	const clientBuild = buildOptions.isBuild ? readClientBuildAssets(buildOptions.root) : {
 		clientEntryUrl: null,
+		islandsEntryUrl: null,
 		cssManifest: {},
 		jsManifest: {}
 	};
 	const adapter = resolved.adapter;
+	const prachtImports = adapter?.serverImports ? adapter.serverImports + "\nimport { prerenderApp } from \"@pracht/core/server\";" : "import { resolveApp, resolveApiRoutes, prerenderApp } 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 islandsGlob = `${resolved.islandsDir}/**/*.{ts,tsx,js,jsx}`;
 	const source = [
-		adapter?.serverImports ? adapter.serverImports + "\nimport { prerenderApp } from \"@pracht/core/server\";" : "import { resolveApp, resolveApiRoutes, prerenderApp } from \"@pracht/core/server\";",
-		isPagesMode ? generatePagesAppInlineSource(resolved, buildOptions.root) : `import { app } from ${JSON.stringify(resolved.appFile)};`,
+		prachtImports,
+		"import { registerServerIslands, setIslandsClientEntryUrl } from \"@pracht/core/server\";",
+		appImport,
 		"",
 		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
 		...createApplyRouteLoaderHintsSource(),
 		registrySource,
 		"",
+		"// Islands are registered eagerly so the server renderer can detect their",
+		"// vnodes during islands-mode renders.",
+		`const islandModules = import.meta.glob(${JSON.stringify(islandsGlob)}, { eager: true });`,
+		"registerServerIslands(islandModules);",
+		`setIslandsClientEntryUrl(${JSON.stringify(islandsEntryUrl ?? void 0)});`,
+		"export const islandFiles = Object.keys(islandModules);",
+		"",
 		"export const resolvedApp = resolveApp(app);",
 		"applyRouteLoaderHints(resolvedApp, routeLoaderHints);",
 		`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 islandsEntryUrl = ${JSON.stringify(islandsEntryUrl ?? null)};`,
 		`export const cssManifest = ${JSON.stringify(clientBuild.cssManifest)};`,
 		`export const jsManifest = ${JSON.stringify(clientBuild.jsManifest)};`,
 		`export const prerenderConcurrency = ${JSON.stringify(resolved.prerenderConcurrency)};`,
@@ -1230,7 +1704,7 @@ function createDevSSRMiddleware(server, options = {}) {
 				apiRoutes: serverMod.apiRoutes,
 				timings
 			});
-			if (response.status === 404) return next();
+			if (response.status === 404 && !routeMatchers.app?.notFound) return next();
 			const contentType = response.headers.get("content-type") ?? "text/html";
 			let body = await response.text();
 			if (contentType.includes("text/html")) body = await server.transformIndexHtml(url, body);
@@ -1302,9 +1776,13 @@ async function handleDevError(server, req, res, next, url, error) {
 * route — the dev middleware then serves the rich dev-only 404 page instead
 * of falling through to Vite. Route-state (JSON) requests and non-document
 * fetches keep their existing 404 behavior.
+*
+* Apps that declare a `notFound` page own their 404s: dev renders that page
+* (exactly as production does) rather than the framework's route table.
 */
 function isDevNotFoundRequest(requestUrl, req, options = {}) {
 	const url = typeof requestUrl === "string" ? new URL(requestUrl, "http://localhost") : requestUrl;
+	if (options.app?.notFound) return false;
 	if (isRouteStateRequest(url, req)) return false;
 	const method = (req.method ?? "GET").toUpperCase();
 	if (method !== "GET" && method !== "HEAD") return false;
@@ -1366,7 +1844,7 @@ function hasKnownAssetExtension(pathname) {
 	return DEV_ASSET_EXTENSIONS.has(extension);
 }
 function isReservedDevPath(pathname) {
-	return pathname === "/@pracht/client.js" || pathname === "/@vite/client" || pathname === "/@react-refresh" || pathname.startsWith("/@vite/") || pathname.startsWith("/@id/") || pathname.startsWith("/@fs/") || pathname.startsWith("/__vite_");
+	return pathname === "/@pracht/client.js" || pathname === "/@pracht/islands.js" || pathname === "/@vite/client" || pathname === "/@react-refresh" || pathname.startsWith("/@vite/") || pathname.startsWith("/@id/") || pathname.startsWith("/@fs/") || pathname.startsWith("/__vite_");
 }
 const NON_DOCUMENT_FETCH_DESTINATIONS = new Set([
 	"audio",
@@ -1453,11 +1931,17 @@ function pracht(options = {}) {
 		config(_config, env) {
 			const isEdge = resolved.adapter.edge === true;
 			const isSSRBuild = env.isSsrBuild;
+			const configRoot = _config.root ?? process.cwd();
+			const wantsIslandsEntry = env.command === "build" && !isSSRBuild && existsSync(resolveConfigPath(configRoot, resolved.islandsDir));
 			return {
 				appType: "custom",
-				...isSSRBuild ? {} : { build: { rollupOptions: { output: { manualChunks(id) {
-					if (id.includes("node_modules/preact") || id.includes("node_modules/preact-suspense")) return "vendor";
-				} } } } },
+				envPrefix: ["VITE_", PUBLIC_ENV_PREFIX],
+				...isSSRBuild ? {} : { build: { rollupOptions: {
+					...wantsIslandsEntry ? { input: [PRACHT_ISLANDS_CLIENT_MODULE_ID] } : {},
+					output: { manualChunks(id) {
+						if (id.includes("node_modules/preact") || id.includes("node_modules/preact-suspense")) return "vendor";
+					} }
+				} } },
 				...isEdge && isSSRBuild ? {
 					ssr: {
 						noExternal: true,
@@ -1472,12 +1956,15 @@ function pracht(options = {}) {
 			isBuild = config.command === "build";
 			routeFileDirs = computeRouteFileDirs(root, resolved);
 		},
-		resolveId(id) {
+		resolveId(id, importer, resolveIdOptions) {
+			if (isIslandsClientModule(id)) return PRACHT_ISLANDS_CLIENT_MODULE_ID;
 			if (isClientModule(id)) return PRACHT_CLIENT_MODULE_ID;
 			if (isServerModule(id)) return PRACHT_SERVER_MODULE_ID;
+			if (id === "@pracht/core/env/server" && !resolveIdOptions?.ssr && !resolveIdOptions?.scan) throw new Error(`[pracht] ${JSON.stringify(SERVER_ENV_MODULE_ID)} was imported by ${JSON.stringify(importer ?? "unknown module")} in client code. serverEnv is server-only — read it inside loaders, middleware, or API routes, or use publicEnv (PRACHT_PUBLIC_-prefixed variables) from "@pracht/core" instead.`);
 			return null;
 		},
 		load(id) {
+			if (isIslandsClientModule(id)) return createPrachtIslandsClientModuleSource(resolved);
 			if (isClientModule(id)) return createPrachtClientModuleSource(resolved, { root });
 			if (isServerModule(id)) return createPrachtServerModuleSource(resolved, {
 				root,
@@ -1520,7 +2007,8 @@ function pracht(options = {}) {
 				resolved.shellsDir,
 				resolved.middlewareDir,
 				resolved.apiDir,
-				resolved.serverDir
+				resolved.serverDir,
+				resolved.islandsDir
 			].some((dir) => relative.startsWith(dir))) {
 				const serverMod = server.moduleGraph.getModuleById(PRACHT_SERVER_MODULE_ID);
 				if (serverMod) server.moduleGraph.invalidateModule(serverMod);
@@ -1528,6 +2016,10 @@ function pracht(options = {}) {
 					const clientMod = server.moduleGraph.getModuleById(PRACHT_CLIENT_MODULE_ID);
 					if (clientMod) server.moduleGraph.invalidateModule(clientMod);
 				}
+				if (relative.startsWith(resolved.islandsDir)) {
+					const islandsMod = server.moduleGraph.getModuleById(PRACHT_ISLANDS_CLIENT_MODULE_ID);
+					if (islandsMod) server.moduleGraph.invalidateModule(islandsMod);
+				}
 			}
 		}
 	};
@@ -1559,7 +2051,8 @@ function pracht(options = {}) {
 		...precompilePlugin ? [precompilePlugin] : [],
 		...preact(),
 		prachtPlugin,
-		clientModuleTransformPlugin
+		clientModuleTransformPlugin,
+		createEnvSafetyPlugin(resolved.envSafety)
 	];
 	const adapterPlugins = resolved.adapter.vitePlugins?.();
 	if (adapterPlugins?.length) plugins.push(...adapterPlugins);
@@ -1582,6 +2075,7 @@ function rewriteManifestCoreImports(code) {
 const PRACHT_OPTIMIZE_DEPS_INCLUDE = [
 	"@pracht/core",
 	"@pracht/core/client",
+	"@pracht/core/islands-client",
 	"@pracht/core/manifest"
 ];
 function createPrachtOptimizeDepsInclude(root) {
@@ -1609,14 +2103,16 @@ function createPrachtOptimizeDepsEntries(resolved) {
 		`${toOptimizeDepsEntry(resolved.pagesDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.middlewareDir)}/**/*.${scriptExtensions}`,
 		`${toOptimizeDepsEntry(resolved.apiDir)}/**/*.{ts,js,tsx,jsx}`,
-		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`
+		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`,
+		`${toOptimizeDepsEntry(resolved.islandsDir)}/**/*.${scriptExtensions}`
 	] : [
 		toOptimizeDepsEntry(resolved.appFile),
 		`${toOptimizeDepsEntry(resolved.routesDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.shellsDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.middlewareDir)}/**/*.${scriptExtensions}`,
 		`${toOptimizeDepsEntry(resolved.apiDir)}/**/*.{ts,js,tsx,jsx}`,
-		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`
+		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`,
+		`${toOptimizeDepsEntry(resolved.islandsDir)}/**/*.${scriptExtensions}`
 	];
 	return [...new Set(entries.filter(Boolean))];
 }
@@ -1684,4 +2180,4 @@ function withTrailingSep(p) {
 	return p.endsWith("/") ? p : `${p}/`;
 }
 //#endregion
-export { PRACHT_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, createPrachtClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, pracht };
+export { PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PUBLIC_ENV_PREFIX, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, formatEnvLeakError, pracht, scanCodeForEnvLeaks };

package/dist/{pages-router-BN3V7ii7.mjs → pages-router-BsVlzz-e.mjs}

@@ -107,6 +107,7 @@ function scan(dir, root, pages) {
 		const routePath = filePathToRoutePath(rel);
 		const source = readFileSync(abs, "utf-8");
 		const renderMode = extractRenderMode(source);
+		const hydrationMode = extractHydrationMode(source);
 		const hasLoader = detectLoaderExport(source);
 		pages.push({
 			absolutePath: abs,
@@ -116,6 +117,7 @@ function scan(dir, root, pages) {
 			isCatchAll: routePath.split("/").includes("*"),
 			isDynamic: routePath.split("/").some((segment) => segment.startsWith(":")),
 			renderMode,
+			hydrationMode,
 			hasLoader
 		});
 	}
@@ -162,6 +164,11 @@ function extractRenderMode(source) {
 	const match = RENDER_MODE_RE.exec(source);
 	return match ? match[1] : void 0;
 }
+const HYDRATION_RE = /export\s+const\s+HYDRATION\s*=\s*["'](\w+)["']/;
+function extractHydrationMode(source) {
+	const match = HYDRATION_RE.exec(source);
+	return match ? match[1] : void 0;
+}
 function generatePagesManifestSource(pages, options) {
 	const pagesDir = options.pagesDir;
 	const defaultRender = options.pagesDefaultRender ?? "ssr";
@@ -170,13 +177,21 @@ function generatePagesManifestSource(pages, options) {
 	const appFile = scanAllFiles(pagesDir).find((f) => basename(f, extname(f)) === "_app" && SHELL_EXTENSIONS.has(extname(f)));
 	const lines = ["import { defineApp, group, route } from \"@pracht/core/manifest\";", ""];
 	const routeEntries = [];
+	const notFoundPage = pages.find((page) => page.routePath === "/404");
 	for (const page of pages) {
+		if (page === notFoundPage) continue;
 		const render = page.renderMode ?? defaultRender;
 		const filePath = prefix ? `${prefix}/${page.relativePath.replace(/\\/g, "/")}` : `./${page.relativePath.replace(/\\/g, "/")}`;
 		const fileRef = useImport ? `() => import(${JSON.stringify(filePath)})` : JSON.stringify(filePath);
 		const metaParts = [`render: ${JSON.stringify(render)}`, `hasLoader: ${page.hasLoader ? "true" : "false"}`];
+		if (page.hydrationMode) metaParts.push(`hydration: ${JSON.stringify(page.hydrationMode)}`);
 		routeEntries.push(`    route(${JSON.stringify(page.routePath)}, ${fileRef}, { ${metaParts.join(", ")} })`);
 	}
+	const notFoundEntry = notFoundPage ? buildNotFoundEntry(notFoundPage, {
+		prefix,
+		useImport,
+		withShell: !!appFile
+	}) : null;
 	if (appFile) {
 		const appPath = prefix ? `${prefix}/_app.${extname(appFile).slice(1)}` : `./${relative(join(pagesDir, ".."), appFile).replace(/\\/g, "/")}`;
 		const shellRef = useImport ? `() => import(${JSON.stringify(appPath)})` : JSON.stringify(appPath);
@@ -189,17 +204,26 @@ function generatePagesManifestSource(pages, options) {
 		lines.push(routeEntries.join(",\n"));
 		lines.push("    ]),");
 		lines.push("  ],");
+		if (notFoundEntry) lines.push(notFoundEntry);
 		lines.push("});");
 	} else {
 		lines.push("const app = defineApp({");
 		lines.push("  routes: [");
 		lines.push(routeEntries.join(",\n"));
 		lines.push("  ],");
+		if (notFoundEntry) lines.push(notFoundEntry);
 		lines.push("});");
 	}
 	lines.push("");
 	return lines.join("\n");
 }
+function buildNotFoundEntry(page, options) {
+	const filePath = options.prefix ? `${options.prefix}/${page.relativePath.replace(/\\/g, "/")}` : `./${page.relativePath.replace(/\\/g, "/")}`;
+	const configParts = [`component: ${options.useImport ? `() => import(${JSON.stringify(filePath)})` : JSON.stringify(filePath)}`];
+	if (options.withShell) configParts.push("shell: \"pages\"");
+	if (page.hydrationMode) configParts.push(`hydration: ${JSON.stringify(page.hydrationMode)}`);
+	return `  notFound: { ${configParts.join(", ")} },`;
+}
 function scanAllFiles(dir) {
 	const results = [];
 	let entries;

package/dist/pages-router.d.mts

@@ -7,6 +7,7 @@ interface ScannedPage {
   isCatchAll: boolean;
   isDynamic: boolean;
   renderMode?: string;
+  hydrationMode?: string;
   hasLoader?: boolean;
 }
 interface PagesRouterOptions {

package/dist/pages-router.mjs

@@ -1,2 +1,2 @@
-import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-BN3V7ii7.mjs";
+import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-BsVlzz-e.mjs";
 export { filePathToRoutePath, generatePagesManifestSource, generateRoutesFile, scanPagesDirectory, sortRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/vite-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Vite plugin for Pracht apps with virtual modules, dev SSR, prerendering, route inspection, and multi-adapter builds.",
   "keywords": [
     "pracht",
@@ -44,9 +44,9 @@
   "dependencies": {
     "@preact/preset-vite": "^2.10.5",
     "@prefresh/vite": "^2.0.0",
-    "@pracht/adapter-node": "0.2.5",
-    "@pracht/core": "0.9.0",
-    "@pracht/preact-ssr-precompile": "0.1.2"
+    "@pracht/adapter-node": "0.3.0",
+    "@pracht/preact-ssr-precompile": "0.1.2",
+    "@pracht/core": "0.10.0"
   },
   "peerDependencies": {
     "vite": "^8.0.0"