@pracht/vite-plugin 0.7.4 → 0.8.0

package/README.md

@@ -86,3 +86,11 @@ Target-specific Vite plugins (e.g. `@cloudflare/vite-plugin`) are pulled in by
 the adapter package you install (`@pracht/adapter-cloudflare`,
 `@pracht/adapter-vercel`, etc.). The default path uses `@pracht/adapter-node`,
 which ships as a dependency of this package.
+
+Custom adapters can expose two separate plugin hooks on `PrachtAdapter`:
+
+- `vitePlugins()` for the platform's normal development and build integration.
+- `graphVitePlugins()` for metadata-only CLI servers. This optional hook must
+  not start runtimes, listeners, persistent workers, or debuggers; use it only
+  for safe resolvers or platform-module stubs. When omitted, graph commands
+  load no adapter-contributed plugins.

package/dist/index.d.mts

@@ -70,6 +70,13 @@ interface PrachtAdapter {
    * Returned plugins are appended to the plugin array returned by `pracht()`.
    */
   vitePlugins?(): Plugin[];
+  /**
+   * Vite plugins that can safely run in the CLI's graph-only server. These
+   * plugins may provide runtime-module stubs or other metadata-only support,
+   * but must not start deployment runtimes, listeners, or persistent workers.
+   * When omitted, graph commands load no adapter-contributed plugins.
+   */
+  graphVitePlugins?(): Plugin[];
   /**
    * If true, the adapter owns dev-server request handling and the vite-plugin
    * will not install its own SSR middleware. Used when the adapter contributes
@@ -103,6 +110,19 @@ interface PrachtLlmsTxtOptions {
   origin?: string;
   /** Sections to emit. Defaults to ["pages", "api", "capabilities"]. */
   include?: LlmsTxtSection[];
+  /**
+   * Route/API path patterns to leave out, using the same segment globs as
+   * `defineApp({ constraints })` (`*` = one segment, trailing `**` = the
+   * rest). llms.txt invites agents to fetch every URL it lists, so exclude
+   * anything an anonymous agent cannot use — pages behind an auth middleware,
+   * internal tooling, deliberate error routes. Capabilities are matched by
+   * their dispatch path (`/api/capabilities/**`).
+   *
+   * ```ts
+   * llmsTxt: { exclude: ["/dashboard", "/admin/**"] }
+   * ```
+   */
+  exclude?: string[];
 }
 interface PrachtPluginOptions {
   appFile?: string;

package/dist/index.mjs

@@ -1,14 +1,15 @@
-import { i as scanPagesDirectory, n as generatePagesManifestSource, o as createRouteLoaderHints } from "./pages-router-CStJY2Zp.mjs";
-import { createRequire } from "node:module";
+import { i as scanPagesDirectory, n as generatePagesManifestSource, o as createRouteLoaderHints } from "./pages-router-BQlG21oC.mjs";
+import { createRequire, isBuiltin } from "node:module";
 import { preactSsrPrecompile } from "@pracht/preact-ssr-precompile";
 import preact from "@preact/preset-vite";
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
 import { loadEnv, parseAst } from "vite";
+import { PRACHT_GRAPH_ONLY_ENV } from "@pracht/core/server";
 import { CAPABILITY_SETTLED_EVENT, CAPABILITY_TRANSPORT_HEADER, CONFIRMATION_HEADER } from "@pracht/capabilities";
-import { extractCapabilityProjection, extractCapabilityRegistrations } from "@pracht/capabilities/static";
+import { extractCapabilityProjection, extractCapabilityRegistrations, extractDefineAppObjectBody, scanTopLevelProperties } from "@pracht/capabilities/static";
 import { createNodeServerEntryModule } from "@pracht/adapter-node";
-import { resolveRegistryModule } from "@pracht/core";
+import { applyDefaultSecurityHeaders, resolveRegistryModule } from "@pracht/core";
 //#region src/client-module-query.ts
 const CLIENT_MODULE_QUERY = "pracht-client";
 const PRACHT_CLIENT_MODULE_QUERY = `?${CLIENT_MODULE_QUERY}`;
@@ -1367,6 +1368,12 @@ function resolveOptions(options) {
 		...options
 	};
 	if (resolved.llmsTxt === void 0) resolved.llmsTxt = false;
+	if (!new Set([
+		"spa",
+		"ssr",
+		"ssg",
+		"isg"
+	]).has(resolved.pagesDefaultRender)) throw new Error("pracht({ pagesDefaultRender }) expects \"spa\", \"ssr\", \"ssg\", or \"isg\".");
 	if (!Number.isInteger(resolved.prerenderConcurrency) || resolved.prerenderConcurrency <= 0) throw new Error("pracht({ prerenderConcurrency }) expects a positive integer.");
 	if (!Number.isInteger(resolved.maxBodySize) || resolved.maxBodySize <= 0) throw new Error("pracht({ maxBodySize }) expects a positive integer number of bytes.");
 	validateBudgets(resolved.budgets);
@@ -1416,6 +1423,82 @@ function validateBudgets(budgets) {
 * rather than silently dropping an endpoint.
 */
 /**
+* Whether the app can reach the agent surface at all — registered capabilities
+* or a `defineApp({ agents })` config. Drives the `__PRACHT_AGENT_SURFACE__`
+* define, which lets the bundler drop the capability and Web Bot Auth runtimes
+* from the server bundle of apps that use neither.
+*
+* Deliberately one-sided: it only answers `false` when the manifest is readable
+* and provably free of both. An unreadable manifest, a parse failure, or any
+* spread inside the manifest file (which could carry registrations this
+* analyzer cannot see) answers `true`, so the runtime keeps deciding for
+* itself. Being wrong the other way would 404 a capability in production that
+* works in dev.
+*/
+function hasAgentSurface(options = {}, root = process.cwd()) {
+	const resolved = resolveOptions(options);
+	if (resolved.pagesDir) return false;
+	const appFileAbs = resolve(root, resolved.appFile.replace(/^\//, ""));
+	let manifestSource;
+	try {
+		manifestSource = readFileSync(appFileAbs, "utf-8");
+	} catch {
+		return true;
+	}
+	const appBody = extractDefineAppObjectBody(manifestSource);
+	if (appBody === null) return true;
+	const properties = scanTopLevelProperties(appBody);
+	if (properties.has("agents") || properties.has("capabilities")) return true;
+	if (/\b(?:agents|capabilities)\b/.test(appBody)) return true;
+	if (appBody.includes("...") || hasOpaqueTopLevelProperty(appBody)) return true;
+	try {
+		return extractCapabilityRegistrations(manifestSource).length > 0;
+	} catch {
+		return true;
+	}
+}
+/** Whether an object literal body contains an opaque key at its top level. */
+function hasOpaqueTopLevelProperty(objectBody) {
+	let braces = 0;
+	let brackets = 0;
+	let parentheses = 0;
+	let expectingKey = true;
+	for (let index = 0; index < objectBody.length; index += 1) {
+		const char = objectBody[index];
+		const next = objectBody[index + 1];
+		if (char === "\"" || char === "'" || char === "`") {
+			const quote = char;
+			for (index += 1; index < objectBody.length; index += 1) if (objectBody[index] === "\\") index += 1;
+			else if (objectBody[index] === quote) break;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			index = objectBody.indexOf("\n", index + 2);
+			if (index === -1) break;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			const end = objectBody.indexOf("*/", index + 2);
+			if (end === -1) return true;
+			index = end + 1;
+			continue;
+		}
+		if (char === "/") return true;
+		const atTopLevel = braces === 0 && brackets === 0 && parentheses === 0;
+		if (atTopLevel && expectingKey && char === "[") return true;
+		if (atTopLevel && expectingKey && char === "\\") return true;
+		if (atTopLevel && char === ":") expectingKey = false;
+		if (atTopLevel && char === ",") expectingKey = true;
+		if (char === "{") braces += 1;
+		else if (char === "}") braces -= 1;
+		else if (char === "[") brackets += 1;
+		else if (char === "]") brackets -= 1;
+		else if (char === "(") parentheses += 1;
+		else if (char === ")") parentheses -= 1;
+	}
+	return false;
+}
+/**
 * Extract capability registrations (name → module path) from the app
 * manifest source and their exposure metadata from each capability source.
 * Pages-router apps have no manifest, so capabilities are manifest-mode only.
@@ -1489,7 +1572,7 @@ function extractCapabilityMetadata(name, file, source) {
 */
 function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions = {}) {
 	const capabilities = extractCapabilities(options, buildOptions.root);
-	const endpoints = {};
+	const endpoints = Object.create(null);
 	for (const capability of capabilities) if (capability.httpPath) endpoints[capability.name] = {
 		method: "POST",
 		path: capability.httpPath,
@@ -1499,7 +1582,9 @@ 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.",
-		`const endpoints = ${JSON.stringify(endpoints)};`,
+		"import { createUseCapability } from \"@pracht/core\";",
+		"",
+		`const endpoints = Object.assign(Object.create(null), JSON.parse(${JSON.stringify(JSON.stringify(endpoints))}));`,
 		"",
 		"export const capabilityEndpoints = endpoints;",
 		"",
@@ -1508,7 +1593,9 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"  try {",
 		"    const headers = new Headers(opts && opts.headers);",
 		"    headers.set(\"content-type\", \"application/json\");",
-		"    if (opts && opts.confirm) {",
+		"    if (opts && opts.prepare) {",
+		`      headers.delete(${JSON.stringify(CONFIRMATION_HEADER)});`,
+		"    } else if (opts && opts.confirm) {",
 		`      headers.set(${JSON.stringify(CONFIRMATION_HEADER)}, opts.confirm);`,
 		"    }",
 		"    response = await fetch(endpoint.path, {",
@@ -1524,8 +1611,9 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"      error: { code: \"network_error\", message: String((error && error.message) || error) },",
 		"    };",
 		"  }",
+		"  let result;",
 		"  try {",
-		"    return await response.json();",
+		"    result = await response.json();",
 		"  } catch {",
 		"    return {",
 		"      ok: false,",
@@ -1535,6 +1623,23 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"      },",
 		"    };",
 		"  }",
+		"  if (",
+		"    !result || typeof result !== \"object\" ||",
+		"    (result.ok !== true && result.ok !== false) ||",
+		"    (result.ok === true && !(\"data\" in result)) ||",
+		"    (result.ok === false &&",
+		"      (!result.error || typeof result.error !== \"object\" ||",
+		"        typeof result.error.code !== \"string\" || typeof result.error.message !== \"string\"))",
+		"  ) {",
+		"    return {",
+		"      ok: false,",
+		"      error: {",
+		"        code: \"invalid_response\",",
+		"        message: `Capability endpoint returned an invalid envelope (status ${response.status}).`,",
+		"      },",
+		"    };",
+		"  }",
+		"  return result;",
 		"}",
 		"",
 		"export async function callCapability(name, input, opts) {",
@@ -1565,6 +1670,38 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"  } catch {}",
 		"  return result;",
 		"}",
+		"",
+		"// Nested client: dotted capability names become object paths, so",
+		"// `capabilities.notes.search(input)` calls `callCapability(\"notes.search\", input)`.",
+		"// Built from the same endpoint table, so there is one dispatch path.",
+		"function buildCapabilityClient(names) {",
+		"  const root = Object.create(null);",
+		"  for (const name of names) {",
+		"    const segments = name.split(\".\");",
+		"    const leaf = segments.pop();",
+		"    let node = root;",
+		"    for (const segment of segments) {",
+		"      // A name that is both a namespace and a leaf (`a` plus `a.b`) would",
+		"      // collide; the namespace wins and the leaf stays reachable through",
+		"      // callCapability(). `pracht verify` reports the shadowed name.",
+		"      if (typeof node[segment] !== \"object\" || node[segment] === null) {",
+		"        node[segment] = Object.create(null);",
+		"      }",
+		"      node = node[segment];",
+		"    }",
+		"    if (typeof node[leaf] !== \"object\") {",
+		"      node[leaf] = (input, opts) => callCapability(name, input, opts);",
+		"    }",
+		"  }",
+		"  return root;",
+		"}",
+		"",
+		"export const capabilities = /*@__PURE__*/ buildCapabilityClient(Object.keys(endpoints));",
+		"",
+		"// The hook's implementation lives in @pracht/core (typed and unit-tested);",
+		"// only the app-specific dispatch is bound here, so every projection shares",
+		"// one call path. Pure-annotated: apps that never call it pay nothing.",
+		"export const useCapability = /*@__PURE__*/ createUseCapability(callCapability);",
 		""
 	].join("\n");
 }
@@ -1884,6 +2021,7 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 	};
 	const adapter = resolved.adapter;
 	const llmsTxtConfig = resolveLlmsTxtConfig(resolved, buildOptions.root);
+	const islandsBootstrapRequired = hasWebmcpCapabilities(resolved, buildOptions.root);
 	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)};`;
@@ -1911,6 +2049,7 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 		`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 islandsBootstrapRequired = ${JSON.stringify(islandsBootstrapRequired)};`,
 		`export const cssManifest = ${JSON.stringify(clientBuild.cssManifest)};`,
 		`export const jsManifest = ${JSON.stringify(clientBuild.jsManifest)};`,
 		`export const prerenderConcurrency = ${JSON.stringify(resolved.prerenderConcurrency)};`,
@@ -1937,12 +2076,14 @@ function createPrachtServerModuleSource(options = {}, buildOptions = {}) {
 function createPrachtDevModuleSource(options = {}, buildOptions = {}) {
 	const resolved = resolveOptions(options);
 	return [
-		"import { resolveApp } from \"@pracht/core/server\";",
+		"import { resolveApp, resolveApiRoutes } from \"@pracht/core/server\";",
 		resolved.pagesDir ? generatePagesAppInlineSource(resolved, buildOptions.root) : `import { app } from ${JSON.stringify(resolved.appFile)};`,
 		"",
 		createPrachtRegistryModuleSource(resolved),
 		"",
 		"export const resolvedApp = resolveApp(app);",
+		`export const apiRoutes = resolveApiRoutes(Object.keys(apiModules), ${JSON.stringify(resolved.apiDir)});`,
+		`export const buildTarget = ${JSON.stringify(resolved.adapter?.id ?? "node")};`,
 		""
 	].join("\n");
 }
@@ -1962,6 +2103,7 @@ function resolveLlmsTxtConfig(resolved, root = process.cwd()) {
 	if (description) config.description = description;
 	if (resolved.llmsTxt.origin) config.origin = resolved.llmsTxt.origin;
 	if (resolved.llmsTxt.include) config.include = resolved.llmsTxt.include;
+	if (resolved.llmsTxt.exclude?.length) config.exclude = resolved.llmsTxt.exclude;
 	return config;
 }
 function createApplyRouteLoaderHintsSource() {
@@ -1997,6 +2139,7 @@ function createRouteLoaderHintsForVirtualModules(options, root = process.cwd())
 }
 function createPrachtRegistryModuleSource(options = {}) {
 	const resolved = resolveOptions(options);
+	const apiGlobs = [`${resolved.apiDir}/**/*.{ts,js,tsx,jsx}`, `!${resolved.apiDir}/**/*.d.ts`];
 	const isPagesMode = !!resolved.pagesDir;
 	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`;
@@ -2012,7 +2155,7 @@ function createPrachtRegistryModuleSource(options = {}) {
 		`  ...import.meta.glob(${JSON.stringify(shellTsrxGlob)}),`,
 		`};`,
 		`export const middlewareModules = import.meta.glob(${JSON.stringify(`${resolved.middlewareDir}/**/*.{ts,tsx,js,jsx}`)});`,
-		`export const apiModules = import.meta.glob(${JSON.stringify(`${resolved.apiDir}/**/*.{ts,js,tsx,jsx}`)});`,
+		`export const apiModules = import.meta.glob(${JSON.stringify(apiGlobs)});`,
 		`export const dataModules = import.meta.glob(${JSON.stringify(`${resolved.serverDir}/**/*.{ts,js,tsx,jsx}`)});`,
 		`export const capabilityModules = import.meta.glob(${JSON.stringify(`${resolved.capabilitiesDir}/**/*.{ts,js,tsx,jsx}`)});`,
 		"",
@@ -2093,6 +2236,9 @@ function createDevSSRMiddleware(server, options = {}) {
 				const llmsTxt = await serverMod.generateLlmsTxt();
 				res.statusCode = 200;
 				res.setHeader("content-type", "text/plain; charset=utf-8");
+				applyDefaultSecurityHeaders(new Headers()).forEach((value, key) => {
+					res.setHeader(key, value);
+				});
 				res.end(llmsTxt);
 				return;
 			}
@@ -2116,12 +2262,14 @@ function createDevSSRMiddleware(server, options = {}) {
 				request: webRequest,
 				debugErrors: true,
 				clientEntryUrl: CLIENT_BROWSER_PATH,
+				islandsEntryUrl: ISLANDS_CLIENT_BROWSER_PATH,
+				islandsBootstrapRequired: serverMod.islandsBootstrapRequired === true,
 				apiRoutes: serverMod.apiRoutes,
 				timings
 			});
 			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") ?? "text/html";
+			const contentType = response.headers.get("content-type") ?? "";
 			let body = await response.text();
 			if (contentType.includes("text/html")) body = await server.transformIndexHtml(url, body);
 			res.statusCode = response.status;
@@ -2442,6 +2590,8 @@ const DEV_ASSET_EXTENSIONS = new Set([
 	".js",
 	".json",
 	".map",
+	".markdown",
+	".md",
 	".mjs",
 	".pdf",
 	".png",
@@ -2500,13 +2650,18 @@ function pracht(options = {}) {
 			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));
+			const wantsIslandsEntry = env.command === "build" && !isSSRBuild && (existsSync(resolveConfigPath(configRoot, resolved.islandsDir)) || hasWebmcpCapabilities(resolved, configRoot));
 			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";
 			return {
 				appType: "custom",
 				envPrefix: ["VITE_", PUBLIC_ENV_PREFIX],
-				define: { __PRACHT_PUBLIC_ENV__: publicEnvDefine },
+				resolve: { dedupe: PREACT_DEDUPE },
+				define: {
+					__PRACHT_PUBLIC_ENV__: publicEnvDefine,
+					__PRACHT_AGENT_SURFACE__: agentSurfaceDefine
+				},
 				...isSSRBuild ? {} : { build: { rollupOptions: {
 					...wantsIslandsEntry ? { input: [PRACHT_ISLANDS_CLIENT_MODULE_ID] } : {},
 					output: { manualChunks(id) {
@@ -2518,6 +2673,15 @@ function pracht(options = {}) {
 						noExternal: true,
 						target: "webworker"
 					},
+					environments: { ssr: { resolve: {
+						conditions: [
+							"worker",
+							"module",
+							"browser",
+							"development|production"
+						],
+						external: ["node:module"]
+					} } },
 					build: { rollupOptions: { external: [/^cloudflare:/] } }
 				} : {}
 			};
@@ -2643,6 +2807,7 @@ function pracht(options = {}) {
 			};
 		}
 	};
+	const edgeRuntimeSafetyPlugin = resolved.adapter.edge ? createEdgeRuntimeSafetyPlugin() : null;
 	const optimizeDepsEntriesPlugin = {
 		name: "pracht:optimize-deps-entries",
 		enforce: "post",
@@ -2659,13 +2824,77 @@ function pracht(options = {}) {
 		...preact(),
 		prachtPlugin,
 		clientModuleTransformPlugin,
+		...edgeRuntimeSafetyPlugin ? [edgeRuntimeSafetyPlugin] : [],
 		createEnvSafetyPlugin(resolved.envSafety)
 	];
-	const adapterPlugins = resolved.adapter.vitePlugins?.();
+	const adapterPlugins = isGraphOnlyMode() ? resolved.adapter.graphVitePlugins?.() : resolved.adapter.vitePlugins?.();
 	if (adapterPlugins?.length) plugins.push(...adapterPlugins);
 	plugins.push(optimizeDepsEntriesPlugin);
 	return plugins;
 }
+function isGraphOnlyMode() {
+	return process.env[PRACHT_GRAPH_ONLY_ENV] === "1";
+}
+function createEdgeRuntimeSafetyPlugin() {
+	let isSsrBuild = false;
+	return {
+		name: "pracht:edge-runtime-safety",
+		apply: "build",
+		enforce: "post",
+		configResolved(config) {
+			isSsrBuild = !!config.build.ssr;
+		},
+		generateBundle(_options, bundle) {
+			const consumer = this.environment?.config?.consumer;
+			if (!(consumer ? consumer === "server" : isSsrBuild)) return;
+			const survivors = [];
+			for (const [fileName, output] of Object.entries(bundle)) {
+				if (output.type !== "chunk") continue;
+				for (const specifier of collectNodeBuiltinImports(this.parse(output.code))) survivors.push({
+					chunk: fileName,
+					specifier
+				});
+			}
+			if (survivors.length === 0) return;
+			this.error([
+				"[pracht] Edge server bundle retains Node.js builtin imports that are unavailable at runtime:",
+				...survivors.map(({ chunk, specifier }) => `  - ${specifier} in ${chunk}`),
+				"Remove the Node-only dependency or move that route to a Node deployment target."
+			].join("\n"));
+		}
+	};
+}
+function collectNodeBuiltinImports(program) {
+	const imports = /* @__PURE__ */ new Set();
+	function sourceValue(node) {
+		if (!node || typeof node !== "object" || !("value" in node)) return null;
+		return typeof node.value === "string" ? node.value : null;
+	}
+	function visit(node) {
+		if (Array.isArray(node)) {
+			for (const item of node) visit(item);
+			return;
+		}
+		if (!node || typeof node !== "object") return;
+		const record = node;
+		const type = record.type;
+		if (type === "ImportDeclaration" || type === "ExportAllDeclaration" || type === "ExportNamedDeclaration" || type === "ImportExpression") {
+			const specifier = sourceValue(record.source);
+			if (specifier && isBuiltin(specifier)) imports.add(specifier);
+		} else if (type === "CallExpression") {
+			const callee = record.callee;
+			const isImport = callee?.type === "Import";
+			const isRequire = callee?.type === "Identifier" && callee.name === "require";
+			if (isImport || isRequire) {
+				const specifier = sourceValue(record.arguments?.[0]);
+				if (specifier && isBuiltin(specifier)) imports.add(specifier);
+			}
+		}
+		for (const value of Object.values(record)) visit(value);
+	}
+	visit(program);
+	return imports;
+}
 const MANIFEST_CORE_IMPORTS = new Set([
 	"defineApp",
 	"group",
@@ -2685,6 +2914,7 @@ const PRACHT_OPTIMIZE_DEPS_INCLUDE = [
 	"@pracht/core/islands-client",
 	"@pracht/core/manifest"
 ];
+const PREACT_DEDUPE = ["preact", "preact-render-to-string"];
 function createPrachtOptimizeDepsInclude(root) {
 	try {
 		if (!toPosixPath(createRequire(join(root, "package.json")).resolve("@pracht/core/package.json")).includes("/node_modules/")) return [];
@@ -2706,10 +2936,12 @@ function withPrachtOptimizeDepsEntries(config, prachtEntries, prachtInclude) {
 function createPrachtOptimizeDepsEntries(resolved) {
 	const scriptExtensions = "{ts,tsx,js,jsx}";
 	const routeExtensions = "{ts,tsx,js,jsx,md,mdx,tsrx}";
+	const apiDir = toOptimizeDepsEntry(resolved.apiDir);
+	const apiEntries = [`${apiDir}/**/*.{ts,js,tsx,jsx}`, `!${apiDir}/**/*.d.ts`];
 	const entries = resolved.pagesDir ? [
 		`${toOptimizeDepsEntry(resolved.pagesDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.middlewareDir)}/**/*.${scriptExtensions}`,
-		`${toOptimizeDepsEntry(resolved.apiDir)}/**/*.{ts,js,tsx,jsx}`,
+		...apiEntries,
 		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`,
 		`${toOptimizeDepsEntry(resolved.islandsDir)}/**/*.${scriptExtensions}`
 	] : [
@@ -2717,7 +2949,7 @@ function createPrachtOptimizeDepsEntries(resolved) {
 		`${toOptimizeDepsEntry(resolved.routesDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.shellsDir)}/**/*.${routeExtensions}`,
 		`${toOptimizeDepsEntry(resolved.middlewareDir)}/**/*.${scriptExtensions}`,
-		`${toOptimizeDepsEntry(resolved.apiDir)}/**/*.{ts,js,tsx,jsx}`,
+		...apiEntries,
 		`${toOptimizeDepsEntry(resolved.serverDir)}/**/*.{ts,js,tsx,jsx}`,
 		`${toOptimizeDepsEntry(resolved.islandsDir)}/**/*.${scriptExtensions}`,
 		`${toOptimizeDepsEntry(resolved.capabilitiesDir)}/**/*.{ts,js,tsx,jsx}`

package/dist/{pages-router-CStJY2Zp.mjs → pages-router-BQlG21oC.mjs}

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
+import { maskCommentsAndStrings } from "@pracht/capabilities/static";
 //#region src/route-loader-hints.ts
 const ROUTE_EXTENSIONS = new Set([
 	".tsx",
@@ -84,6 +85,8 @@ const SHELL_EXTENSIONS = new Set([
 function scanPagesDirectory(pagesDir) {
 	const pages = [];
 	scan(pagesDir, pagesDir, pages);
+	const appShell = pages.find((page) => page.routePath === "__shell__");
+	if (appShell?.hasRevalidateExport) throw new Error(`[pracht] Pages app shell ${JSON.stringify(appShell.relativePath)} exports REVALIDATE, but app shells are not ISG routes. Declare the policy on each ISG page instead.`);
 	return sortRoutes(pages);
 }
 function scan(dir, root, pages) {
@@ -105,10 +108,11 @@ function scan(dir, root, pages) {
 		if (name.startsWith("_") && name !== "_app") continue;
 		const rel = relative(root, abs);
 		const routePath = filePathToRoutePath(rel);
-		const source = readFileSync(abs, "utf-8");
-		const renderMode = extractRenderMode(source);
-		const hydrationMode = extractHydrationMode(source);
-		const hasLoader = detectLoaderExport(source);
+		const analysisSource = maskMarkdownFences(readFileSync(abs, "utf-8"), rel);
+		const renderMode = extractQuotedPageExport(analysisSource, "RENDER_MODE", rel);
+		const hydrationMode = extractQuotedPageExport(analysisSource, "HYDRATION", rel);
+		const revalidate = extractRevalidateSeconds(analysisSource, rel);
+		const hasLoader = detectLoaderExport(analysisSource);
 		pages.push({
 			absolutePath: abs,
 			relativePath: rel,
@@ -118,6 +122,8 @@ function scan(dir, root, pages) {
 			isDynamic: routePath.split("/").some((segment) => segment.startsWith(":")),
 			renderMode,
 			hydrationMode,
+			revalidateSeconds: revalidate.seconds,
+			hasRevalidateExport: revalidate.present,
 			hasLoader
 		});
 	}
@@ -159,15 +165,70 @@ function getRouteSegmentSpecificity(segment) {
 	if (segment.startsWith(":")) return 2;
 	return 3;
 }
-const RENDER_MODE_RE = /export\s+const\s+RENDER_MODE\s*=\s*["'](\w+)["']/;
-function extractRenderMode(source) {
-	const match = RENDER_MODE_RE.exec(source);
-	return match ? match[1] : void 0;
+function extractQuotedPageExport(source, name, relativePath) {
+	const declarations = [...maskCommentsAndStrings(source).matchAll(new RegExp(`export\\s+const\\s+${name}\\s*=`, "g"))];
+	if (declarations.length === 0) return void 0;
+	if (declarations.length > 1) throw new Error(`[pracht] Pages route ${JSON.stringify(relativePath)} exports ${name} more than once.`);
+	const declaration = declarations[0];
+	const valueStart = (declaration.index ?? 0) + declaration[0].length;
+	return source.slice(valueStart).trimStart().match(/^["'](\w+)["']/)?.[1];
 }
-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;
+const REVALIDATE_RE = /export\s+const\s+REVALIDATE\s*=\s*([^;\n]+)/;
+function extractRevalidateSeconds(source, relativePath) {
+	const matches = [...maskCommentsAndStrings(source).matchAll(new RegExp(REVALIDATE_RE, "g"))];
+	if (matches.length === 0) return { present: false };
+	if (matches.length > 1) throw new Error(`[pracht] Pages route ${JSON.stringify(relativePath)} exports REVALIDATE more than once.`);
+	const expression = matches[0][1].trim().replace(/\s+as\s+const$/, "");
+	if (!/^\d(?:_?\d)*$/.test(expression)) throw new Error(`[pracht] Pages route ${JSON.stringify(relativePath)} must export REVALIDATE as a positive integer literal number of seconds (for example, \`export const REVALIDATE = 60\`).`);
+	const seconds = Number(expression.replaceAll("_", ""));
+	if (!Number.isSafeInteger(seconds) || seconds <= 0) throw new Error(`[pracht] Pages route ${JSON.stringify(relativePath)} must export REVALIDATE as a positive integer literal number of seconds within JavaScript's safe integer range.`);
+	return {
+		present: true,
+		seconds
+	};
+}
+/** Mask Markdown fenced examples while preserving source offsets and top-level MDX exports. */
+function maskMarkdownFences(source, relativePath) {
+	if (!/\.mdx?$/.test(relativePath)) return source;
+	const chars = source.split("");
+	let activeFence = null;
+	for (const line of source.matchAll(/.*(?:\r?\n|$)/g)) {
+		if (line[0] === "") continue;
+		const lineStart = line.index ?? 0;
+		const stripped = stripMarkdownContainerPrefix(line[0].replace(/\r?\n$/, ""));
+		const fenceContent = activeFence && stripped.content.startsWith(" ".repeat(activeFence.continuationIndent)) ? stripped.content.slice(activeFence.continuationIndent) : stripped.content;
+		const opening = activeFence ? null : /^ {0,3}(`{3,}|~{3,})/.exec(fenceContent);
+		const closing = activeFence ? new RegExp(`^ {0,3}\\${activeFence.character}{${activeFence.length},}[ \\t]*$`).test(fenceContent) : false;
+		if (activeFence || opening) for (let offset = 0; offset < line[0].length; offset += 1) {
+			const index = lineStart + offset;
+			if (chars[index] !== "\n" && chars[index] !== "\r") chars[index] = " ";
+		}
+		if (closing) activeFence = null;
+		else if (opening) activeFence = {
+			character: opening[1][0],
+			continuationIndent: stripped.continuationIndent,
+			length: opening[1].length
+		};
+	}
+	return chars.join("");
+}
+function stripMarkdownContainerPrefix(line) {
+	let content = line;
+	let continuationIndent = 0;
+	while (true) {
+		const quote = /^ {0,3}> ?/.exec(content);
+		if (quote) {
+			content = content.slice(quote[0].length);
+			continue;
+		}
+		const list = /^ {0,3}(?:[-+*]|\d{1,9}[.)])[ \t]+/.exec(content);
+		if (!list) return {
+			content,
+			continuationIndent
+		};
+		continuationIndent += list[0].length;
+		content = content.slice(list[0].length);
+	}
 }
 function generatePagesManifestSource(pages, options) {
 	const pagesDir = options.pagesDir;
@@ -175,16 +236,20 @@ function generatePagesManifestSource(pages, options) {
 	const prefix = options.pagesDirPrefix;
 	const useImport = options.useImportSyntax ?? false;
 	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 lines = [`import { ${pages.some((page) => page.revalidateSeconds !== void 0) ? "defineApp, group, route, timeRevalidate" : "defineApp, group, route"} } from "@pracht/core/manifest";`, ""];
 	const routeEntries = [];
 	const notFoundPage = pages.find((page) => page.routePath === "/404");
+	if (notFoundPage?.hasRevalidateExport) throw new Error(`[pracht] Pages not-found module ${JSON.stringify(notFoundPage.relativePath)} exports REVALIDATE, but not-found responses are never ISG routes.`);
 	for (const page of pages) {
 		if (page === notFoundPage) continue;
 		const render = page.renderMode ?? defaultRender;
+		if (render === "isg" && page.revalidateSeconds === void 0) throw new Error(`[pracht] Pages route ${JSON.stringify(page.relativePath)} uses render mode "isg" but does not export a revalidation policy. Add \`export const REVALIDATE = 60\` with a positive integer number of seconds, or use another render mode.`);
+		if (render !== "isg" && page.hasRevalidateExport) throw new Error(`[pracht] Pages route ${JSON.stringify(page.relativePath)} exports REVALIDATE but its effective render mode is ${JSON.stringify(render)}. REVALIDATE is only valid with \`RENDER_MODE = "isg"\` (or \`pagesDefaultRender: "isg"\`).`);
 		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)}`);
+		if (page.revalidateSeconds !== void 0) metaParts.push(`revalidate: timeRevalidate(${page.revalidateSeconds})`);
 		routeEntries.push(`    route(${JSON.stringify(page.routePath)}, ${fileRef}, { ${metaParts.join(", ")} })`);
 	}
 	const notFoundEntry = notFoundPage ? buildNotFoundEntry(notFoundPage, {

package/dist/pages-router.d.mts

@@ -8,6 +8,8 @@ interface ScannedPage {
   isDynamic: boolean;
   renderMode?: string;
   hydrationMode?: string;
+  revalidateSeconds?: number;
+  hasRevalidateExport?: boolean;
   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-CStJY2Zp.mjs";
+import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-BQlG21oC.mjs";
 export { filePathToRoutePath, generatePagesManifestSource, generateRoutesFile, scanPagesDirectory, sortRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/vite-plugin",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Vite plugin for Pracht apps with virtual modules, dev SSR, prerendering, route inspection, and multi-adapter builds.",
   "keywords": [
     "pracht",
@@ -44,10 +44,10 @@
   "dependencies": {
     "@preact/preset-vite": "^2.10.5",
     "@prefresh/vite": "^2.0.0",
-    "@pracht/core": "0.11.3",
-    "@pracht/adapter-node": "0.3.6",
-    "@pracht/preact-ssr-precompile": "0.1.2",
-    "@pracht/capabilities": "0.1.1"
+    "@pracht/adapter-node": "0.3.9",
+    "@pracht/capabilities": "0.2.0",
+    "@pracht/core": "0.13.0",
+    "@pracht/preact-ssr-precompile": "0.1.3"
   },
   "peerDependencies": {
     "vite": "^8.0.0"