@pracht/vite-plugin 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -135,8 +135,53 @@ interface PrachtLlmsTxtOptions {
    * ```
    */
   exclude?: string[];
+  /**
+   * Ceiling on how many prerendered instances a single dynamic route
+   * contributes to the Pages section. Defaults to 50; `0` lists every
+   * instance.
+   *
+   * The instances kept are the first ones `getStaticPaths()` returns, after
+   * `exclude` is applied — the author's order, which for a blog is usually
+   * newest-first.
+   *
+   * llms.txt is an index, not a sitemap. A 5,000-post blog expanded through
+   * `getStaticPaths()` produces a 5,000-line, 180 KB file — larger than most
+   * agent context budgets. Truncation is never silent: a line above the Pages
+   * section names the route and the ratio it lists.
+   */
+  maxPagesPerRoute?: number;
+}
+/**
+ * Optional client-router features, compiled out of the client bundle when
+ * disabled. Every one defaults to `true`. Turn a feature off only when the app
+ * really does not use it: the router silently stops honouring the
+ * corresponding route options and `<Link>` props.
+ */
+interface PrachtClientOptions {
+  /**
+   * JS prefetching of route-state JSON and route/shell chunks, driven by
+   * `route({ prefetch })` and `<Link prefetch>`. Off also drops the separate
+   * prefetch chunk the router loads on every page, and makes the imperative
+   * `prefetch()` export a no-op.
+   */
+  prefetch?: boolean;
 }
 interface PrachtPluginOptions {
+  /**
+   * Switch off client-router features the app does not use, so they are
+   * compiled out of the client bundle. See {@link PrachtClientOptions}.
+   */
+  client?: PrachtClientOptions;
+  /**
+   * Group the Preact runtime into a shared `vendor` chunk. Defaults to `true`.
+   *
+   * The group is appended to whatever `build.rollupOptions.output` chunking
+   * the app configures, so app-level grouping and the framework chunk compose
+   * (see `frameworkChunkGroups()`). Set `false` to contribute nothing at all —
+   * for an app that places `frameworkChunkGroups()` itself, or one that wants
+   * Preact merged into its own chunks.
+   */
+  vendorChunk?: boolean;
   appFile?: string;
   routesDir?: string;
   shellsDir?: string;
@@ -198,6 +243,50 @@ interface PrachtPluginOptions {
   llmsTxt?: false | PrachtLlmsTxtOptions;
 }
 //#endregion
+//#region src/chunk-groups.d.ts
+/**
+ * Pracht's client chunking policy, expressed as something an app can build on.
+ *
+ * The framework has exactly one opinion here: Preact belongs in its own chunk,
+ * shared by every route and cached across deploys that only change app code.
+ * Everything else about chunking is the app's call — merging the long tail of
+ * small initial chunks, splitting a heavy dependency out of a route, grouping
+ * by feature.
+ *
+ * Those two have to coexist, and under Rolldown that is not automatic:
+ * `output.codeSplitting` makes `manualChunks` and `advancedChunks` ignored
+ * outright, so a plugin that hard-codes one form silently deletes whichever
+ * form the app used. Pracht therefore looks at what the app configured and
+ * contributes its group in the same form, as one entry appended to the app's
+ * list rather than as a replacement for it.
+ *
+ * Precedence follows Rolldown's own rule — higher `priority` first, then
+ * declaration order. The app's groups are declared first, so an app group that
+ * would also capture Preact wins at equal priority, and pracht's group only
+ * takes what nothing else claimed. To keep the framework chunk intact while
+ * merging everything around it, give the app group a `test` that excludes
+ * Preact, or raise pracht's group by placing {@link frameworkChunkGroups}
+ * explicitly and setting `vendorChunk: false`.
+ */
+/** Name of the chunk pracht groups the Preact runtime into. */
+declare const FRAMEWORK_VENDOR_CHUNK = "vendor";
+interface ChunkGroup {
+  name: string;
+  test?: RegExp | string;
+  priority?: number;
+  minSize?: number;
+  [option: string]: unknown;
+}
+/**
+ * Pracht's chunk groups, as a fresh array an app can place in its own
+ * `output.codeSplitting.groups`.
+ *
+ * Use this together with `pracht({ vendorChunk: false })` when the framework
+ * group has to sit somewhere other than last — pracht then contributes no
+ * chunking config of its own and the app's list is the whole policy.
+ */
+declare function frameworkChunkGroups(): ChunkGroup[];
+//#endregion
 //#region src/plugin-codegen.d.ts
 declare function createPrachtClientModuleSource(options?: PrachtPluginOptions, buildOptions?: {
   root?: string;
@@ -224,10 +313,12 @@ interface ExtractedCapability {
   name: string;
   /** Manifest-relative module path, e.g. "./capabilities/notes-search.ts". */
   file: string;
+  title: string;
   description: string;
   effect: string | null;
   httpPath: string | null;
   webmcp: boolean;
+  webmcpUntrustedContent: boolean;
   inputSchema: Record<string, unknown> | null;
 }
 /**
@@ -256,9 +347,17 @@ declare function createPrachtCapabilitiesClientModuleSource(options?: PrachtPlug
  * validation/middleware/policy stays server-side. Each dispatch carries the
  * transport marker header so audit events can attribute it to WebMCP.
  *
- * Targets the Chrome origin-trial API: `document.modelContext.registerTool()`
- * (Chrome 150+; `navigator.modelContext` is the deprecated pre-150 location
- * and is kept as a fallback). No-ops silently when the API is absent.
+ * Targets the WebMCP CG draft API: `document.modelContext.registerTool()`
+ * (ChatGPT desktop's built-in browser; Chromium 150+ within the 149–156
+ * origin trial — the `document` getter landed in 150 and the deprecated
+ * `navigator.modelContext` alias was removed in 152, so trial builds before
+ * 150 are not targeted and no fallback is kept; current polyfills install the
+ * `document` shape). No-ops silently when the API is absent.
+ *
+ * `execute()` returns the capability envelope (`{ ok, data }` /
+ * `{ ok: false, error }`) as a plain object: per the spec the host serializes
+ * the returned value itself, so wrapping it in MCP-style content blocks would
+ * reach the agent double-encoded.
  */
 declare function createPrachtWebmcpModuleSource(options?: PrachtPluginOptions, buildOptions?: {
   root?: string;
@@ -267,4 +366,4 @@ declare function createPrachtWebmcpModuleSource(options?: PrachtPluginOptions, b
 //#region src/index.d.ts
 declare function pracht(options?: PrachtPluginOptions): Plugin[];
 //#endregion
-export { type EnvLeakReference, type EnvSafetyOptions, type LlmsTxtSection, PRACHT_CAPABILITIES_MODULE_ID, PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PRACHT_WEBMCP_MODULE_ID, PUBLIC_ENV_PREFIX, type PrachtAdapter, type PrachtLlmsTxtOptions, type PrachtPluginOptions, type RenderMode, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtCapabilitiesClientModuleSource, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, createPrachtWebmcpModuleSource, extractCapabilities, formatEnvLeakError, pracht, scanCodeForEnvLeaks };
+export { type ChunkGroup, type EnvLeakReference, type EnvSafetyOptions, FRAMEWORK_VENDOR_CHUNK, type LlmsTxtSection, PRACHT_CAPABILITIES_MODULE_ID, PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PRACHT_WEBMCP_MODULE_ID, PUBLIC_ENV_PREFIX, type PrachtAdapter, type PrachtClientOptions, type PrachtLlmsTxtOptions, type PrachtPluginOptions, type RenderMode, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtCapabilitiesClientModuleSource, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, createPrachtWebmcpModuleSource, extractCapabilities, formatEnvLeakError, frameworkChunkGroups, pracht, scanCodeForEnvLeaks };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-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 { c as createRouteLoaderHints, d as LEGACY_BARE_ROUTE_EXTENSIONS, f as extensionGlob, i as scanPagesDirectory, l as createRouteStaticPathsHints, m as withAdditionalExtensions, n as generatePagesManifestSource, o as createRouteHeadHints, p as normalizeAdditionalExtensions, s as createRouteHeadersHints, u as DEFAULT_ROUTE_EXTENSIONS } from "./pages-router-MA9rOl88.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import { preactSsrPrecompile } from "@pracht/preact-ssr-precompile";
 import preact from "@preact/preset-vite";
@@ -6,6 +6,7 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "n
 import { dirname, extname, join, resolve } from "node:path";
 import { loadEnv, parseAst } from "vite";
 import { PRACHT_GRAPH_ONLY_ENV } from "@pracht/core/server";
+import { DEV_ROUTE_DATA_STALE_EVENT } from "@pracht/core/client";
 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";
@@ -26,6 +27,47 @@ function stripPrachtClientModuleQuery(id) {
 	const query = id.slice(queryStart + 1).split("&").filter((part) => part !== CLIENT_MODULE_QUERY);
 	return query.length > 0 ? `${path}?${query.join("&")}` : path;
 }
+/** Extensions `@prefresh/vite` accepts: `/\.(c|m)?(t|j)sx?$/`, anchored at end. */
+const PREFRESH_EXTENSION_RE = /\.((?:c|m)?[tj]sx?)$/i;
+function isPrefreshCompatibleId(id) {
+	return PREFRESH_EXTENSION_RE.test(id);
+}
+/**
+* The id to hand `@prefresh/vite` for a pracht client module.
+*
+* Prefresh uses the id for exactly three things: its `/\.(c|m)?(t|j)sx?$/`
+* filter, a `/\.tsx?$/` check that picks the TypeScript parser plugin, and the
+* key it embeds in the `$RefreshReg$` it injects. A query-carrying id fails the
+* first two, which is why route and shell modules got no Fast Refresh at all —
+* but simply stripping the query fails the third: one file under `src/routes`
+* can reach the browser as *two* module instances, once through the route glob
+* as `…/x.tsx?pracht-client` and once as a plain import from a sibling route.
+* Both would then register under the same key, and `@prefresh/core` treats a
+* second `register()` for a known key with a different function object as a
+* pending component replacement — which the next unrelated Fast Refresh
+* flushes, tearing down and re-running the untouched copy's effects.
+*
+* A reserved, length-prefixed namespace keeps the real extension last, so the
+* filter and parser check still pass, while giving each complete module id its
+* own registration key. Keeping the authored id verbatim makes the mapping
+* injective; keeping it behind a non-file prefix prevents a real sibling such
+* as `x.pracht-client.tsx` from colliding with the synthetic key. The id is
+* never resolved against the filesystem; the JSX dev transform has already
+* stamped `_jsxFileName` from the real id by the time prefresh runs, so dev
+* source locations and open-in-editor are unaffected.
+*
+* Compiled formats whose real extension prefresh rejects (`.md`, `.mdx`, and
+* configured additional formats) instead keep that extension in the basename
+* and receive a synthetic `.jsx`. Their companion Vite plugin has already
+* turned the authored format into JavaScript by the time this id is used.
+*/
+function toPrachtClientPrefreshId(id) {
+	const stripped = stripPrachtClientModuleQuery(id);
+	const queryStart = stripped.indexOf("?");
+	const path = queryStart === -1 ? stripped : stripped.slice(0, queryStart);
+	const parserExtension = PREFRESH_EXTENSION_RE.exec(path)?.[1] ?? "jsx";
+	return `pracht-client:${id.length}:${id}.${parserExtension}`;
+}
 function getRolldownLang(id) {
 	const path = stripPrachtClientModuleQuery(id).split("?")[0];
 	if (/\.(c|m)?tsx$/i.test(path)) return "tsx";
@@ -892,6 +934,87 @@ function enqueueDependencies(target, dependencies) {
 	for (const name of dependencies) target.add(name);
 }
 //#endregion
+//#region src/chunk-groups.ts
+/**
+* Pracht's client chunking policy, expressed as something an app can build on.
+*
+* The framework has exactly one opinion here: Preact belongs in its own chunk,
+* shared by every route and cached across deploys that only change app code.
+* Everything else about chunking is the app's call — merging the long tail of
+* small initial chunks, splitting a heavy dependency out of a route, grouping
+* by feature.
+*
+* Those two have to coexist, and under Rolldown that is not automatic:
+* `output.codeSplitting` makes `manualChunks` and `advancedChunks` ignored
+* outright, so a plugin that hard-codes one form silently deletes whichever
+* form the app used. Pracht therefore looks at what the app configured and
+* contributes its group in the same form, as one entry appended to the app's
+* list rather than as a replacement for it.
+*
+* Precedence follows Rolldown's own rule — higher `priority` first, then
+* declaration order. The app's groups are declared first, so an app group that
+* would also capture Preact wins at equal priority, and pracht's group only
+* takes what nothing else claimed. To keep the framework chunk intact while
+* merging everything around it, give the app group a `test` that excludes
+* Preact, or raise pracht's group by placing {@link frameworkChunkGroups}
+* explicitly and setting `vendorChunk: false`.
+*/
+/**
+* Modules that make up the framework runtime's vendor chunk.
+*
+* `[\\/]` rather than `/` so the group matches on Windows, and no trailing
+* boundary so the Preact family — `preact/hooks`, `preact-suspense`,
+* `preact-render-to-string` — lands in one chunk with Preact itself.
+*/
+const FRAMEWORK_VENDOR_TEST = /node_modules[\\/]preact/;
+/** Name of the chunk pracht groups the Preact runtime into. */
+const FRAMEWORK_VENDOR_CHUNK = "vendor";
+/**
+* Pracht's chunk groups, as a fresh array an app can place in its own
+* `output.codeSplitting.groups`.
+*
+* Use this together with `pracht({ vendorChunk: false })` when the framework
+* group has to sit somewhere other than last — pracht then contributes no
+* chunking config of its own and the app's list is the whole policy.
+*/
+function frameworkChunkGroups() {
+	return [{
+		name: FRAMEWORK_VENDOR_CHUNK,
+		test: FRAMEWORK_VENDOR_TEST
+	}];
+}
+/** Whether a module id belongs in the framework vendor chunk. */
+function isFrameworkVendorModule(id) {
+	return FRAMEWORK_VENDOR_TEST.test(id);
+}
+/**
+* Build the chunking config pracht contributes, given what the app configured.
+*
+* Returns a partial `output` because Vite merges a plugin's `config()` result
+* over the user config and concatenates arrays: returning only pracht's group
+* is what appends it to the app's list instead of replacing it.
+*/
+function frameworkChunkConfig(output) {
+	if (Array.isArray(output)) return { warning: "build.rollupOptions.output is an array, so pracht did not add its Preact vendor chunk group. Add frameworkChunkGroups() from @pracht/vite-plugin to each output's codeSplitting.groups to keep the framework chunk." };
+	const options = output ?? {};
+	if (options.codeSplitting === false) return {};
+	const groups = frameworkChunkGroups();
+	if (options.codeSplitting === void 0) {
+		if (isRecord(options.advancedChunks)) return { output: { advancedChunks: { groups } } };
+		if (typeof options.manualChunks === "function") {
+			const appManualChunks = options.manualChunks;
+			return { output: { manualChunks(id, meta) {
+				if (isFrameworkVendorModule(id)) return FRAMEWORK_VENDOR_CHUNK;
+				return appManualChunks(id, meta);
+			} } };
+		}
+	}
+	return { output: { codeSplitting: { groups } } };
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/env-safety.ts
 /**
 * Env vars Vite defines on `import.meta.env` in every bundle, plus NODE_ENV
@@ -1220,6 +1343,116 @@ function createEnvSafetyPlugin(envSafety) {
 	};
 }
 //#endregion
+//#region src/client-module-prefresh.ts
+/**
+* Give route and shell modules Preact Fast Refresh.
+*
+* `@prefresh/vite` gates its transform on `/\.(c|m)?(t|j)sx?$/`, a pattern
+* anchored at the end of the id — so an id carrying a query never matches.
+* Pracht loads route and shell modules in the browser through
+* `import.meta.glob(..., { query: "?pracht-client" })` so its post transform
+* can strip server-only exports, which means the module the browser actually
+* runs is `/src/routes/home.tsx?pracht-client`. Prefresh skipped it, no
+* `import.meta.hot.accept` was injected, and with no self-accepting boundary
+* the update propagated to the non-accepting virtual client entry: every edit
+* to a route or a shell became a full page reload with client state loss.
+* Components outside those directories were unaffected, which is why this hid
+* for so long — Fast Refresh worked everywhere except the files a route-based
+* framework is mostly made of.
+*
+* Running after `pracht:client-module-transform` (both are `post`; array order
+* decides) is deliberate: prefresh sees the stripped module, whose exports are
+* only components, rather than the authored one where a co-located `loader`
+* would stop it self-accepting anyway.
+*
+* The id prefresh is handed is synthetic — see `toPrachtClientPrefreshId`. It
+* must satisfy prefresh's extension filter *and* stay distinct from the id of
+* the authored file, because the same file can be in the client graph twice and
+* the id doubles as prefresh's component registration key.
+*/
+function createClientModulePrefreshPlugin(preactPlugins, config = {}) {
+	const transform = resolvePrefreshTransform(preactPlugins);
+	if (!transform) return null;
+	return {
+		name: "pracht:client-module-prefresh",
+		enforce: "post",
+		apply: "serve",
+		async transform(code, id, transformOptions) {
+			if (transformOptions?.ssr) return null;
+			const carriesClientQuery = isPrachtClientModuleId(id);
+			const isBareCompiledFormat = !carriesClientQuery && !isPrefreshCompatibleId(id) && config.isRouteOrShellModule?.(id) === true;
+			if (!carriesClientQuery && !isBareCompiledFormat) return null;
+			return await transform.call(this, code, toPrachtClientPrefreshId(id), transformOptions);
+		}
+	};
+}
+/**
+* `@preact/preset-vite` returns a plugin array whose shape is its own business;
+* find prefresh by name rather than by position, and treat its absence as "no
+* Fast Refresh configured" rather than an error.
+*/
+function resolvePrefreshTransform(preactPlugins) {
+	for (const plugin of flattenPlugins(preactPlugins)) {
+		if (plugin.name !== "prefresh") continue;
+		const transform = plugin.transform;
+		if (typeof transform === "function") return transform;
+		if (transform && typeof transform === "object" && "handler" in transform) return transform.handler;
+	}
+	return null;
+}
+function flattenPlugins(plugins) {
+	const flat = [];
+	const visit = (option) => {
+		if (!option || typeof option.then === "function") return;
+		if (Array.isArray(option)) {
+			for (const nested of option) visit(nested);
+			return;
+		}
+		if (typeof option === "object" && "name" in option) flat.push(option);
+	};
+	for (const plugin of plugins) visit(plugin);
+	return flat;
+}
+//#endregion
+//#region src/head-hint-reload.ts
+/**
+* Which changed files reach routes with generated client hints.
+*
+* Head and response-header hints decide whether a dependency edit must reload
+* the document; loader hints decide whether it must re-fetch active route data.
+* The importer walk is shared because all three are keyed by route source.
+*/
+function toPosixPath$2(path) {
+	return path.replace(/\\/g, "/");
+}
+function reachesRouteHintedModule(modules, serverRoot, routeHints, options = {}) {
+	const pending = options.startAtImporters ? modules.flatMap((module) => [...module.importers ?? []]) : [...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$2(modulePath);
+			if (routeHints[normalizedPath.startsWith(serverRoot) ? normalizedPath.slice(serverRoot.length) : normalizedPath] === true) return true;
+		}
+		if (module.importers) pending.push(...module.importers);
+	}
+	return false;
+}
+//#endregion
+//#region src/route-data-stale.ts
+function sendRouteDataStale(server) {
+	const hot = server.environments?.client?.hot;
+	if (!hot) return false;
+	hot.send({
+		type: "custom",
+		event: DEV_ROUTE_DATA_STALE_EVENT
+	});
+	return true;
+}
+//#endregion
 //#region src/hot-update-reload.ts
 /**
 * True when `file` participates in server rendering but has no runtime
@@ -1351,7 +1584,10 @@ function createDefaultNodeAdapter() {
 }
 //#endregion
 //#region src/plugin-options.ts
+const CLIENT_FEATURE_DEFAULTS = { prefetch: true };
 const DEFAULTS = {
+	client: CLIENT_FEATURE_DEFAULTS,
+	vendorChunk: true,
 	appFile: "/src/routes.ts",
 	middlewareDir: "/src/middleware",
 	routesDir: "/src/routes",
@@ -1377,6 +1613,8 @@ function resolveOptions(options) {
 		...options
 	};
 	if (resolved.llmsTxt === void 0) resolved.llmsTxt = false;
+	resolved.client = resolveClientOptions(options.client);
+	if (typeof resolved.vendorChunk !== "boolean") throw new Error(`pracht({ vendorChunk }) expects a boolean, got ${JSON.stringify(resolved.vendorChunk)}.`);
 	resolved.additionalExtensions = normalizeAdditionalExtensions(resolved.additionalExtensions);
 	if (!new Set([
 		"spa",
@@ -1390,6 +1628,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",
@@ -1401,6 +1653,10 @@ function validateLlmsTxt(llmsTxt) {
 	if (llmsTxt.include !== void 0) {
 		if (!(Array.isArray(llmsTxt.include) && llmsTxt.include.every((section) => LLMS_TXT_SECTIONS.has(section)))) throw new Error(`pracht({ llmsTxt: { include } }) expects an array of "pages", "api", and/or "capabilities", got ${JSON.stringify(llmsTxt.include)}.`);
 	}
+	if (llmsTxt.maxPagesPerRoute !== void 0) {
+		const value = llmsTxt.maxPagesPerRoute;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new Error(`pracht({ llmsTxt: { maxPagesPerRoute } }) expects a non-negative integer (0 lists every page), got ${JSON.stringify(value)}.`);
+	}
 }
 function validateBudgets(budgets) {
 	for (const [key, value] of Object.entries(budgets)) {
@@ -1592,7 +1848,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, withBase } from \"@pracht/core\";",
+		"import { createUseCapability, ensureCapabilityRevalidation, withBase } from \"@pracht/core\";",
 		"",
 		`const endpoints = Object.assign(Object.create(null), JSON.parse(${JSON.stringify(JSON.stringify(endpoints))}));`,
 		"",
@@ -1653,6 +1909,7 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 		"}",
 		"",
 		"export async function callCapability(name, input, opts) {",
+		"  ensureCapabilityRevalidation();",
 		"  const endpoint = endpoints[name];",
 		"  if (!endpoint) {",
 		"    return {",
@@ -1722,16 +1979,30 @@ function createPrachtCapabilitiesClientModuleSource(options = {}, buildOptions =
 * validation/middleware/policy stays server-side. Each dispatch carries the
 * transport marker header so audit events can attribute it to WebMCP.
 *
-* Targets the Chrome origin-trial API: `document.modelContext.registerTool()`
-* (Chrome 150+; `navigator.modelContext` is the deprecated pre-150 location
-* and is kept as a fallback). No-ops silently when the API is absent.
+* Targets the WebMCP CG draft API: `document.modelContext.registerTool()`
+* (ChatGPT desktop's built-in browser; Chromium 150+ within the 149–156
+* origin trial — the `document` getter landed in 150 and the deprecated
+* `navigator.modelContext` alias was removed in 152, so trial builds before
+* 150 are not targeted and no fallback is kept; current polyfills install the
+* `document` shape). No-ops silently when the API is absent.
+*
+* `execute()` returns the capability envelope (`{ ok, data }` /
+* `{ ok: false, error }`) as a plain object: per the spec the host serializes
+* the returned value itself, so wrapping it in MCP-style content blocks would
+* reach the agent double-encoded.
 */
 function createPrachtWebmcpModuleSource(options = {}, buildOptions = {}) {
 	const tools = extractCapabilities(options, buildOptions.root).filter((capability) => capability.webmcp).map((capability) => ({
 		name: capability.name,
+		...capability.title ? { title: capability.title } : {},
 		description: capability.description,
-		effect: capability.effect,
-		inputSchema: capability.inputSchema
+		inputSchema: capability.inputSchema,
+		annotations: {
+			readOnlyHint: capability.effect === "read",
+			...capability.effect === "read" ? { destructiveHint: false } : {},
+			idempotentHint: capability.effect === "read",
+			...capability.webmcpUntrustedContent ? { untrustedContentHint: true } : {}
+		}
 	}));
 	return [
 		"// Generated by @pracht/vite-plugin — WebMCP page-tool registration shim.",
@@ -1742,30 +2013,27 @@ function createPrachtWebmcpModuleSource(options = {}, buildOptions = {}) {
 		"",
 		"export function registerPrachtWebmcpTools() {",
 		"  const modelContext =",
-		"    (typeof document !== \"undefined\" && document.modelContext) ||",
-		"    (typeof navigator !== \"undefined\" && navigator.modelContext) ||",
-		"    null;",
+		"    (typeof document !== \"undefined\" && document.modelContext) || null;",
 		"  if (!modelContext || typeof modelContext.registerTool !== \"function\") {",
 		"    return false;",
 		"  }",
 		"  for (const tool of tools) {",
 		"    try {",
 		"      const registration = modelContext.registerTool({",
-		"        name: tool.name,",
-		"        description: tool.description,",
-		"        inputSchema: tool.inputSchema,",
-		"        annotations: { readOnlyHint: tool.effect === \"read\" },",
-		"        async execute(input) {",
-		"          const result = await callCapability(tool.name, input, { headers: transportHeaders });",
-		"          return { content: [{ type: \"text\", text: JSON.stringify(result) }] };",
+		"        ...tool,",
+		"        async execute(input, { signal } = {}) {",
+		"          return callCapability(tool.name, input, {",
+		"            headers: transportHeaders,",
+		"            signal,",
+		"          });",
 		"        },",
 		"      });",
 		"      if (registration && typeof registration.catch === \"function\") {",
 		"        registration.catch(() => {});",
 		"      }",
 		"    } catch {",
-		"      // Origin-trial API surface may shift; a failed registration must",
-		"      // never break the page.",
+		"      // The API is still an origin-trial surface; a failed registration",
+		"      // must never break the page.",
 		"    }",
 		"  }",
 		"  return true;",
@@ -1783,10 +2051,7 @@ function createPrachtWebmcpModuleSource(options = {}, buildOptions = {}) {
 function createWebmcpBootstrapSource() {
 	return [
 		"// WebMCP page tools — loaded only when the browser exposes the API.",
-		"if (",
-		"  typeof document !== \"undefined\" &&",
-		"  (document.modelContext || (typeof navigator !== \"undefined\" && navigator.modelContext))",
-		") {",
+		"if (typeof document !== \"undefined\" && document.modelContext) {",
 		"  import(\"virtual:pracht/webmcp\").catch(() => {});",
 		"}",
 		""
@@ -1907,7 +2172,7 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 	const appFilePosix = resolved.appFile.replace(/\\/g, "/").replace(/^\.\//, "");
 	const appDir = (appFilePosix.startsWith("/") ? appFilePosix : `/${appFilePosix}`).replace(/\/[^/]*$/, "") || "/";
 	return [
-		"import { resolveApp, initClientRouter, readHydrationState } from \"@pracht/core/client\";",
+		"import { resolveApp, initClientRouter, readHydrationState, DEV_ROUTE_DATA_STALE_EVENT, refreshDevRouteData } from \"@pracht/core/client\";",
 		appImport,
 		"",
 		`const routeLoaderHints = ${JSON.stringify(routeLoaderHints)};`,
@@ -1992,6 +2257,18 @@ function createPrachtClientModuleSource(options = {}, buildOptions = {}) {
 		"  });",
 		"}",
 		"",
+		"// A route module's loader, head, and getStaticPaths are stripped",
+		"// out of the browser copy, so Fast Refresh patching the component in place",
+		"// leaves the page holding data the server would no longer send. The dev",
+		"// server says when that happened; re-fetching route state is what the full",
+		"// page reload used to deliver as a side effect. This entry is the only",
+		"// module in the graph with an import.meta.hot of its own — an installed",
+		"// @pracht/core is a pre-bundled dependency and has none. Production builds",
+		"// replace import.meta.hot with undefined and drop the whole branch.",
+		"if (import.meta.hot) {",
+		"  import.meta.hot.on(DEV_ROUTE_DATA_STALE_EVENT, refreshDevRouteData);",
+		"}",
+		"",
 		...hasWebmcpCapabilities(resolved, buildOptions.root) ? createWebmcpBootstrapSource() : []
 	].join("\n");
 }
@@ -2130,6 +2407,7 @@ function resolveLlmsTxtConfig(resolved, root = process.cwd()) {
 	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;
+	if (resolved.llmsTxt.maxPagesPerRoute !== void 0) config.maxPagesPerRoute = resolved.llmsTxt.maxPagesPerRoute;
 	return config;
 }
 function createApplyRouteLoaderHintsSource() {
@@ -2171,6 +2449,19 @@ function createRouteHeadHintsForVirtualModules(options, root = process.cwd()) {
 		rootRelativePrefix: prefix
 	})));
 }
+function createRouteHeadersHintsForVirtualModules(options, root = process.cwd()) {
+	if (options.pagesDir) return createRouteHeadersHints(resolve(root, options.pagesDir.slice(1)), {
+		additionalExtensions: options.additionalExtensions,
+		rootRelativePrefix: options.pagesDir
+	});
+	const appFileDir = dirname(resolve(root, options.appFile.slice(1)));
+	const directories = [[options.routesDir, resolve(root, options.routesDir.slice(1))], [options.shellsDir, resolve(root, options.shellsDir.slice(1))]];
+	return Object.assign({}, ...directories.map(([prefix, directory]) => createRouteHeadersHints(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
@@ -2202,6 +2493,19 @@ function createRouteLoaderHintsForVirtualModules(options, root = process.cwd())
 		rootRelativePrefix: options.routesDir
 	});
 }
+/**
+* Server data modules that can own a separately wired route loader.
+*
+* These hints stay on the dev-server side: unlike the per-route table above,
+* the generated browser entry has no use for data-module filenames. The HMR
+* importer walk does, though — a shared module can be client-reachable through
+* a component and server-reachable through `route(..., { loader })`, so it
+* cannot rely on the server-only full-reload fallback.
+*/
+function createServerLoaderHintsForHotUpdates(options, root = process.cwd()) {
+	const hints = createRouteLoaderHints(resolve(root, options.serverDir.slice(1)), { rootRelativePrefix: options.serverDir });
+	return Object.fromEntries(Object.entries(hints).filter((entry) => entry[1] === true));
+}
 function createPrachtRegistryModuleSource(options = {}) {
 	const resolved = resolveOptions(options);
 	const apiGlobs = [`${resolved.apiDir}/**/*.{ts,js,tsx,jsx}`, `!${resolved.apiDir}/**/*.d.ts`];
@@ -2258,6 +2562,38 @@ function generatePagesAppInlineSource(options, root = process.cwd()) {
 	pagesAppSourceCache.set(cacheKey, source);
 	return source;
 }
+function createAgentTrafficBuffer(limit = 200) {
+	const capacity = Math.max(1, Math.floor(limit));
+	const events = [];
+	let recorded = 0;
+	return {
+		record(event) {
+			recorded += 1;
+			events.push({
+				at: Date.now(),
+				capability: event.capability,
+				effect: event.effect,
+				transport: event.transport,
+				via: event.via,
+				outcome: event.outcome,
+				status: event.status,
+				durationMs: event.durationMs,
+				agent: event.agent ? {
+					agentDomain: event.agent.agentDomain,
+					keyId: event.agent.keyId
+				} : null
+			});
+			while (events.length > capacity) events.shift();
+		},
+		snapshot() {
+			return {
+				limit: capacity,
+				recorded,
+				events: [...events].reverse()
+			};
+		}
+	};
+}
 //#endregion
 //#region src/plugin-dev-ssr.ts
 const BODYLESS_METHODS = new Set(["GET", "HEAD"]);
@@ -2307,6 +2643,7 @@ function createDevSSRMiddleware(server, options = {}) {
 	const withDevBase = (path) => devBase === "/" || !path.startsWith("/") ? path : `${devBase}${path.slice(1)}`;
 	let warnedDevtoolsCollision = false;
 	let warnedLlmsTxtCollision = false;
+	const agentTraffic = createAgentTrafficBuffer();
 	if (options.llmsTxt && typeof server.config.publicDir === "string") {
 		if (existsSync(join(server.config.publicDir, "llms.txt"))) server.config.logger.warn("[pracht] Both public/llms.txt and the pracht({ llmsTxt }) option are present. Dev serves the static public/llms.txt, but \"pracht build\" overwrites it with the generated content. Remove one to avoid a dev/production mismatch.");
 	}
@@ -2327,6 +2664,7 @@ function createDevSSRMiddleware(server, options = {}) {
 					server.config.logger.warn(`[pracht] An app route matches ${requestUrl.pathname}, which is reserved for the pracht devtools page in dev. The devtools page wins during development; the app route is only served in production builds.`);
 				}
 				await serveDevtools(server, res, {
+					agentTraffic,
 					apiRoutes: serverMod.apiRoutes ?? [],
 					app: serverMod.resolvedApp,
 					base: devBase,
@@ -2363,16 +2701,25 @@ function createDevSSRMiddleware(server, options = {}) {
 				throw err;
 			}
 			const timings = {};
+			let routeError;
+			let capturedRouteError = false;
+			let routeErrorContext;
 			const response = await framework.handlePrachtRequest({
 				app: serverMod.resolvedApp,
 				registry: serverMod.registry,
 				request: webRequest,
 				debugErrors: true,
+				onRouteError: (error, _requestPath, context) => {
+					capturedRouteError = true;
+					routeError = error;
+					routeErrorContext = context;
+				},
 				clientEntryUrl: withDevBase(CLIENT_BROWSER_PATH),
 				islandsEntryUrl: withDevBase(ISLANDS_CLIENT_BROWSER_PATH),
 				islandsBootstrapRequired: serverMod.islandsBootstrapRequired === true,
 				apiRoutes: serverMod.apiRoutes,
-				timings
+				timings,
+				onCapabilityAudit: agentTraffic.record
 			});
 			const responseContentType = response.headers.get("content-type") ?? "";
 			if (response.status === 404 && !responseContentType.includes("application/json") && !routeMatchers.app?.notFound) return next();
@@ -2396,6 +2743,17 @@ function createDevSSRMiddleware(server, options = {}) {
 				source.pipe(res);
 				return;
 			}
+			if (shouldRenderDevErrorOverlay({
+				capturedRouteError,
+				contentType,
+				exposeServerErrors: shouldExposeDevServerErrors(),
+				hasErrorBoundary: routeErrorContext?.errorBoundary != null,
+				status: response.status
+			})) {
+				const serverTiming = framework.formatServerTimingHeader(timings);
+				await respondWithErrorOverlay(server, res, url, routeError, routeErrorContext, devBase, response.status, serverTiming);
+				return;
+			}
 			let body = await response.text();
 			if (contentType.includes("text/html")) body = await transformDevHtml(server, url, body, devBase);
 			res.statusCode = response.status;
@@ -2614,27 +2972,100 @@ function escapeHtmlAttribute(value) {
 */
 async function serveDevtools(server, res, options) {
 	const devtools = await server.ssrLoadModule("@pracht/core/devtools");
-	const capabilityModules = (await server.ssrLoadModule(PRACHT_SERVER_MODULE_ID)).registry?.capabilityModules;
+	const serverModule = await server.ssrLoadModule(PRACHT_SERVER_MODULE_ID);
+	const capabilityModules = serverModule.registry?.capabilityModules;
+	const middlewareModules = serverModule.registry?.middlewareModules;
 	const graph = await devtools.buildAppGraph({
 		apiRoutes: options.apiRoutes,
 		app: options.app,
 		loadModule: async (file) => {
 			return await resolveRegistryModule(capabilityModules, file) ?? server.ssrLoadModule(file);
 		},
+		loadSetupModule: async (file) => {
+			return await resolveRegistryModule(middlewareModules, file) ?? server.ssrLoadModule(file);
+		},
+		verifyMcpTokenVerifier: async () => {
+			const auth = options.app.agents?.mcp?.auth;
+			if (!auth) return;
+			await (await server.ssrLoadModule("@pracht/core/server")).loadMcpTokenVerifier(auth, serverModule.registry ?? {});
+		},
 		readSource: (file) => readFileSync(resolve(server.config.root, `.${file}`), "utf-8")
 	});
+	const agentTraffic = options.agentTraffic.snapshot();
 	if (options.wantsJson) {
 		res.statusCode = 200;
 		res.setHeader("content-type", "application/json; charset=utf-8");
-		res.end(JSON.stringify(graph, null, 2));
+		res.end(JSON.stringify({
+			...graph,
+			agentTraffic
+		}, null, 2));
 		return;
 	}
-	let html = devtools.buildDevtoolsHtml(graph, { base: options.base });
+	let html = devtools.buildDevtoolsHtml(graph, {
+		agentTraffic,
+		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);
 }
+/**
+* True when a dev response should be replaced by the error overlay.
+*
+* The runtime only falls back to `text/plain` for a page render when neither
+* the route nor its shell declares an ErrorBoundary. When one does, the
+* response is the app's own error UI (`text/html`) and dev must leave it
+* alone. Route-state and capability failures are JSON and belong to the
+* client router, not to a human reading a document.
+*/
+function shouldRenderDevErrorOverlay(options) {
+	return options.capturedRouteError && options.exposeServerErrors && !options.hasErrorBoundary && options.status >= 500 && options.contentType.toLowerCase().startsWith("text/plain");
+}
+/**
+* The dev middleware passes `debugErrors: true` unconditionally, but the
+* runtime refuses to honor it when `NODE_ENV === "production"` (see
+* `shouldExposeServerErrors` in @pracht/core) — a dev server started inside a
+* container that exports `NODE_ENV=production` must not answer with internals.
+* The overlay is built from the raw error rather than from the runtime's
+* already-redacted body, so it has to repeat that check.
+*/
+function shouldExposeDevServerErrors() {
+	return (typeof process !== "undefined" ? process.env?.NODE_ENV : void 0) !== "production";
+}
+/**
+* Render a failed page render as the dev error overlay.
+*
+* `handlePrachtRequest` answers a render/loader/middleware failure with the
+* runtime's plain-text fallback whenever no ErrorBoundary claims it. In a
+* production adapter that is correct — a browser is not the audience. In dev
+* the browser *is* the audience, and the fallback is at its worst exactly when
+* it matters most: a compiler diagnostic arrives colourized for a terminal, so
+* `text/plain` renders every escape sequence literally.
+*/
+async function respondWithErrorOverlay(server, res, url, error, context, base, status, serverTiming) {
+	if (error instanceof Error) server.ssrFixStacktrace(error);
+	const { buildErrorOverlayHtml } = await server.ssrLoadModule("@pracht/core/error-overlay");
+	let html = buildErrorOverlayHtml({
+		message: error instanceof Error ? error.message : String(error),
+		stack: error instanceof Error ? error.stack : void 0,
+		routeId: context?.routeId,
+		file: context?.routeFile,
+		loaderFile: context?.loaderFile,
+		shellFile: context?.shellFile,
+		phase: context?.phase,
+		root: server.config.root,
+		base
+	});
+	html = await server.transformIndexHtml(url, html);
+	res.statusCode = status;
+	res.setHeader("content-type", "text/html; charset=utf-8");
+	applyDefaultSecurityHeaders(new Headers()).forEach((value, key) => {
+		res.setHeader(key, value);
+	});
+	if (serverTiming) res.setHeader("Server-Timing", serverTiming);
+	res.end(html);
+}
 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") {
@@ -2814,28 +3245,15 @@ async function nodeToWebRequest(req, maxBodySize, base = "/") {
 }
 //#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 = {};
+	let clientRouteHeadersHints = {};
+	let clientRouteLoaderHints = {};
+	let serverRouteLoaderHints = {};
 	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.");
@@ -2845,6 +3263,7 @@ function pracht(options = {}) {
 	const prachtPlugin = {
 		name: "pracht",
 		enforce: "pre",
+		api: { llmsTxtEnabled: Boolean(resolved.llmsTxt) },
 		config(_config, env) {
 			const isEdge = resolved.adapter.edge === true;
 			const isSSRBuild = env.isSsrBuild;
@@ -2854,6 +3273,9 @@ function pracht(options = {}) {
 			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) };
+			const clientChunkConfig = isSSRBuild || !resolved.vendorChunk ? {} : frameworkChunkConfig(_config.build?.rollupOptions?.output);
+			if (clientChunkConfig.warning) console.warn(`[pracht] ${clientChunkConfig.warning}`);
 			return {
 				appType: "custom",
 				envPrefix: ["VITE_", PUBLIC_ENV_PREFIX],
@@ -2861,13 +3283,12 @@ function pracht(options = {}) {
 				define: {
 					__PRACHT_PUBLIC_ENV__: publicEnvDefine,
 					__PRACHT_AGENT_SURFACE__: agentSurfaceDefine,
-					__PRACHT_STATIC_TARGET__: staticTargetDefine
+					__PRACHT_STATIC_TARGET__: staticTargetDefine,
+					...clientFeatureDefines
 				},
 				...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";
-					} }
+					...clientChunkConfig.output ? { output: clientChunkConfig.output } : {}
 				} } },
 				...isEdge && isSSRBuild ? {
 					ssr: {
@@ -2885,7 +3306,7 @@ function pracht(options = {}) {
 					} } },
 					build: { rollupOptions: { external: [/^cloudflare:/] } }
 				} : {},
-				...!isEdge && isSSRBuild ? { ssr: { noExternal: [PRACHT_SSR_NO_EXTERNAL] } } : {}
+				...!isEdge && isSSRBuild || env.command === "serve" ? { ssr: { noExternal: [PRACHT_SSR_NO_EXTERNAL] } } : {}
 			};
 		},
 		configResolved(config) {
@@ -2910,6 +3331,9 @@ function pracht(options = {}) {
 			if (isIslandsClientModule(id)) return createPrachtIslandsClientModuleSource(resolved, { root });
 			if (isClientModule(id)) {
 				clientRouteHeadHints = createRouteHeadHintsForVirtualModules(resolved, root);
+				clientRouteHeadersHints = createRouteHeadersHintsForVirtualModules(resolved, root);
+				clientRouteLoaderHints = createRouteLoaderHintsForVirtualModules(resolved, root);
+				serverRouteLoaderHints = createServerLoaderHintsForHotUpdates(resolved, root);
 				return createPrachtClientModuleSource(resolved, { root });
 			}
 			if (isDevModule(id)) return createPrachtDevModuleSource(resolved, {
@@ -2963,24 +3387,58 @@ function pracht(options = {}) {
 			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;
+			const changesRouteLoaderSource = isPagesMode ? relative.startsWith(resolved.pagesDir) : relative.startsWith(resolved.routesDir);
+			const previousServerRouteLoaderHints = serverRouteLoaderHints;
+			if (!isPagesMode && relative.startsWith(resolved.serverDir)) try {
+				serverRouteLoaderHints = createServerLoaderHintsForHotUpdates(resolved, root);
+			} catch {}
+			const loaderDependencyHints = {
+				...clientRouteLoaderHints,
+				...previousServerRouteLoaderHints,
+				...serverRouteLoaderHints
+			};
+			const changesRouteHeadDependency = reachesRouteHintedModule(modules, serverRoot, clientRouteHeadHints, { startAtImporters: changesRouteHeadSource });
+			const changesRouteHeadersDependency = reachesRouteHintedModule(modules, serverRoot, clientRouteHeadersHints, { startAtImporters: changesRouteHeadSource });
+			const changesRouteLoaderDependency = reachesRouteHintedModule(modules, serverRoot, loaderDependencyHints, { startAtImporters: changesRouteLoaderSource });
+			let shouldReloadClientEntry = changesRouteHeadDependency || changesRouteHeadersDependency;
 			let clientHeadModule;
-			if (changesRouteHeadSource || changesRouteHeadDependency) clientHeadModule = server.moduleGraph.getModuleById(PRACHT_CLIENT_MODULE_ID);
+			if (changesRouteHeadSource || changesRouteHeadDependency || changesRouteHeadersDependency) clientHeadModule = server.moduleGraph.getModuleById(PRACHT_CLIENT_MODULE_ID);
 			if (changesRouteHeadSource) {
-				const previousHint = clientRouteHeadHints[relative];
+				const previousHint = clientRouteHeadHints[relative] === true;
 				try {
 					const nextHints = createRouteHeadHintsForVirtualModules(resolved, root);
-					shouldReloadClientHead ||= previousHint === true || nextHints[relative] === true;
+					shouldReloadClientEntry ||= previousHint !== (nextHints[relative] === true);
 					clientRouteHeadHints = nextHints;
 				} catch {
-					shouldReloadClientHead = true;
+					shouldReloadClientEntry = true;
 				}
 			} else if (changesRouteHeadDependency && clientHeadModule) server.moduleGraph.invalidateModule(clientHeadModule);
+			if (changesRouteHeadSource) {
+				const previouslyHadHeaders = clientRouteHeadersHints[relative] === true;
+				try {
+					const nextHints = createRouteHeadersHintsForVirtualModules(resolved, root);
+					shouldReloadClientEntry ||= previouslyHadHeaders || nextHints[relative] === true;
+					clientRouteHeadersHints = nextHints;
+				} catch {
+					shouldReloadClientEntry = true;
+				}
+			}
+			if (changesRouteLoaderSource) {
+				const previousHint = clientRouteLoaderHints[relative] === true;
+				try {
+					const nextHints = createRouteLoaderHintsForVirtualModules(resolved, root);
+					shouldReloadClientEntry ||= previousHint !== (nextHints[relative] === true);
+					clientRouteLoaderHints = nextHints;
+				} catch {
+					shouldReloadClientEntry = true;
+				}
+			}
 			if (isPagesMode && relative.startsWith(resolved.pagesDir)) {
 				clearPagesAppSourceCache();
 				invalidateVirtualModules(server);
-				if (!sendServerOnlyFullReload(server, file) && shouldReloadClientHead && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
+				const sentFullReload = sendServerOnlyFullReload(server, file);
+				if (!sentFullReload && !shouldReloadClientEntry) sendRouteDataStale(server);
+				if (!sentFullReload && shouldReloadClientEntry && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
 				return;
 			}
 			if (!isPagesMode && relative === resolved.appFile) {
@@ -3018,7 +3476,9 @@ function pracht(options = {}) {
 					if (capabilityMod) server.moduleGraph.invalidateModule(capabilityMod);
 				}
 			}
-			if (!sendServerOnlyFullReload(server, file) && shouldReloadClientHead && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
+			const sentFullReload = sendServerOnlyFullReload(server, file);
+			if (!sentFullReload && shouldReloadClientEntry && clientHeadModule) return [...new Set([...modules, clientHeadModule])];
+			if (!sentFullReload && (changesRouteHeadSource || changesRouteLoaderDependency)) sendRouteDataStale(server);
 		}
 	};
 	const configuredBasePlugin = {
@@ -3056,12 +3516,15 @@ function pracht(options = {}) {
 		...resolved.precompileSsrJsx === true ? {} : resolved.precompileSsrJsx,
 		ssrOnly: true
 	}) : null;
+	const preactPlugins = preact();
+	const clientModulePrefreshPlugin = createClientModulePrefreshPlugin(preactPlugins, { isRouteOrShellModule: (id) => isRouteOrShellFile(id, routeFileDirs, routeFileExtensions) });
 	const plugins = [
 		...precompilePlugin ? [precompilePlugin] : [],
-		...preact(),
+		...preactPlugins,
 		prachtPlugin,
 		configuredBasePlugin,
 		clientModuleTransformPlugin,
+		...clientModulePrefreshPlugin ? [clientModulePrefreshPlugin] : [],
 		...edgeRuntimeSafetyPlugin ? [edgeRuntimeSafetyPlugin] : [],
 		createEnvSafetyPlugin(resolved.envSafety)
 	];
@@ -3315,4 +3778,4 @@ function withTrailingSep(p) {
 	return p.endsWith("/") ? p : `${p}/`;
 }
 //#endregion
-export { PRACHT_CAPABILITIES_MODULE_ID, PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PRACHT_WEBMCP_MODULE_ID, PUBLIC_ENV_PREFIX, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtCapabilitiesClientModuleSource, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, createPrachtWebmcpModuleSource, extractCapabilities, formatEnvLeakError, pracht, scanCodeForEnvLeaks };
+export { FRAMEWORK_VENDOR_CHUNK, PRACHT_CAPABILITIES_MODULE_ID, PRACHT_CLIENT_MODULE_ID, PRACHT_ISLANDS_CLIENT_MODULE_ID, PRACHT_SERVER_MODULE_ID, PRACHT_WEBMCP_MODULE_ID, PUBLIC_ENV_PREFIX, VITE_BUILTIN_ENV_VARS, createEnvSafetyPlugin, createPrachtCapabilitiesClientModuleSource, createPrachtClientModuleSource, createPrachtIslandsClientModuleSource, createPrachtRegistryModuleSource, createPrachtServerModuleSource, createPrachtWebmcpModuleSource, extractCapabilities, formatEnvLeakError, frameworkChunkGroups, pracht, scanCodeForEnvLeaks };

package/dist/{pages-router-KcCRkhnf.mjs → pages-router-MA9rOl88.mjs}

@@ -46,6 +46,7 @@ function namedDeclarationRe(exportName) {
 	return new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+${exportName}\\b`);
 }
 const HEAD_DECLARATION_RE = namedDeclarationRe("head");
+const HEADERS_DECLARATION_RE = namedDeclarationRe("headers");
 const STATIC_PATHS_DECLARATION_RE = namedDeclarationRe("getStaticPaths");
 const EXPORT_BLOCK_RE = /export\s*\{([^}]*)\}\s*(?:from\s*["'][^"']+["'])?/g;
 const EXPORT_ALL_RE = /export\s+\*\s+from\b/;
@@ -168,10 +169,13 @@ function exportSpecifiersInclude(specifiers, exportName) {
 * Whether `source` exports `exportName`, via a declaration, an export block,
 * or an `export *` re-export (which could expose anything, so it counts).
 *
-* Comments and strings are masked first, so prose or a string literal
-* mentioning the name cannot produce a false positive.
+* Ordinary TS/JS is parsed exactly, including string-literal export names.
+* Custom syntaxes fall back to masked lexical detection so prose or a string
+* literal mentioning the name cannot produce a false positive.
 */
 function detectNamedExport(source, exportName, declarationRe) {
+	const parsedResult = inspectParsedModule(source, exportName);
+	if (parsedResult !== void 0) return parsedResult;
 	const analysisSource = maskCommentsAndStrings(source);
 	if (declarationRe.test(analysisSource) || variableDeclarationExports(analysisSource, exportName)) return true;
 	for (const match of analysisSource.matchAll(EXPORT_BLOCK_RE)) if (exportSpecifiersInclude(match[1], exportName)) return true;
@@ -180,6 +184,10 @@ function detectNamedExport(source, exportName, declarationRe) {
 function detectHeadExport(source) {
 	return detectNamedExport(source, "head", HEAD_DECLARATION_RE);
 }
+/** Whether the route or shell module exports document response headers. */
+function detectHeadersExport(source) {
+	return detectNamedExport(source, "headers", HEADERS_DECLARATION_RE);
+}
 /**
 * Whether the route module exports `getStaticPaths()`.
 *
@@ -195,25 +203,25 @@ function detectStaticPathsExport(source) {
 function isSyntaxNode(value) {
 	return typeof value === "object" && value !== null && typeof value.type === "string";
 }
-function bindingIncludesLoader(node) {
+function bindingIncludesName(node, exportName) {
 	if (!isSyntaxNode(node)) return false;
-	if (node.type === "Identifier") return node.name === "loader";
-	if (node.type === "AssignmentPattern") return bindingIncludesLoader(node.left);
-	if (node.type === "RestElement") return bindingIncludesLoader(node.argument);
-	if (node.type === "ArrayPattern") return Array.isArray(node.elements) && node.elements.some(bindingIncludesLoader);
+	if (node.type === "Identifier") return node.name === exportName;
+	if (node.type === "AssignmentPattern") return bindingIncludesName(node.left, exportName);
+	if (node.type === "RestElement") return bindingIncludesName(node.argument, exportName);
+	if (node.type === "ArrayPattern") return Array.isArray(node.elements) && node.elements.some((element) => bindingIncludesName(element, exportName));
 	if (node.type === "ObjectPattern") return Array.isArray(node.properties) && node.properties.some((property) => {
 		if (!isSyntaxNode(property)) return false;
-		return property.type === "RestElement" ? bindingIncludesLoader(property.argument) : bindingIncludesLoader(property.value);
+		return property.type === "RestElement" ? bindingIncludesName(property.argument, exportName) : bindingIncludesName(property.value, exportName);
 	});
 	return false;
 }
-function exportedNameIsLoader(node) {
+function exportedNameMatches(node, exportName) {
 	if (!isSyntaxNode(node)) return false;
-	if (node.type === "Identifier") return node.name === "loader";
-	if (node.type === "StringLiteral") return node.value === "loader";
+	if (node.type === "Identifier") return node.name === exportName;
+	if (node.type === "StringLiteral") return node.value === exportName;
 	return false;
 }
-function inspectParsedModule(source) {
+function inspectParsedModule(source, exportName) {
 	for (const plugins of [["typescript", "jsx"], ["typescript"]]) {
 		let body;
 		try {
@@ -230,19 +238,19 @@ function inspectParsedModule(source) {
 				continue;
 			}
 			if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
-			if (Array.isArray(statement.specifiers) && statement.specifiers.some((specifier) => isSyntaxNode(specifier) && specifier.exportKind !== "type" && exportedNameIsLoader(specifier.exported))) return true;
+			if (Array.isArray(statement.specifiers) && statement.specifiers.some((specifier) => isSyntaxNode(specifier) && specifier.exportKind !== "type" && exportedNameMatches(specifier.exported, exportName))) return true;
 			const declaration = statement.declaration;
 			if (!isSyntaxNode(declaration)) continue;
 			if (declaration.declare === true || declaration.type.startsWith("TS")) continue;
 			if (declaration.type === "VariableDeclaration") {
-				if (Array.isArray(declaration.declarations) && declaration.declarations.some((declarator) => isSyntaxNode(declarator) && bindingIncludesLoader(declarator.id))) return true;
-			} else if (bindingIncludesLoader(declaration.id)) return true;
+				if (Array.isArray(declaration.declarations) && declaration.declarations.some((declarator) => isSyntaxNode(declarator) && bindingIncludesName(declarator.id, exportName))) return true;
+			} else if (bindingIncludesName(declaration.id, exportName)) return true;
 		}
 		return false;
 	}
 }
 function detectLoaderExport(source) {
-	const parsedResult = inspectParsedModule(source);
+	const parsedResult = inspectParsedModule(source, "loader");
 	if (parsedResult !== void 0) return parsedResult;
 	try {
 		const [imports, exports] = parse$1(source);
@@ -309,6 +317,26 @@ function createRouteHeadHints(routesDir, options = {}) {
 	}
 	return hints;
 }
+function createRouteHeadersHints(routesDir, options = {}) {
+	const files = [];
+	const hints = {};
+	const additionalExtensions = normalizeAdditionalExtensions(options.additionalExtensions);
+	scanRouteFiles(routesDir, files, withAdditionalExtensions(DEFAULT_ROUTE_EXTENSIONS, additionalExtensions));
+	for (const file of files) {
+		const extension = extname(file);
+		const hasHeaders = extension === ".md" || extension === ".mdx" || additionalExtensions.includes(extension) || detectHeadersExport(readFileSync(file, "utf-8"));
+		const relativeToRoutesDir = toPosixPath(relative(routesDir, file));
+		const routeRootPrefix = options.rootRelativePrefix?.replace(/\/$/, "");
+		const keys = /* @__PURE__ */ new Set();
+		if (options.appFileDir) {
+			const relativeToAppFile = toPosixPath(relative(options.appFileDir, file));
+			keys.add(relativeToAppFile.startsWith(".") ? relativeToAppFile : `./${relativeToAppFile}`);
+		}
+		if (routeRootPrefix) keys.add(`${routeRootPrefix}/${relativeToRoutesDir}`);
+		for (const key of keys) hints[key] = hasHeaders;
+	}
+	return hints;
+}
 /**
 * Per-route-file `getStaticPaths()` presence, keyed the same way as the loader
 * and head hints.
@@ -375,6 +403,7 @@ function scan(dir, root, pages, pageExtensions, shellExtensions, additionalExten
 		const revalidate = extractRevalidateSeconds(analysisSource, rel);
 		const hasLoader = detectLoaderExport(analysisSource);
 		const hasHead = ext === ".md" || ext === ".mdx" || additionalExtensions.has(ext) || detectHeadExport(analysisSource);
+		const hasHeaders = ext === ".md" || ext === ".mdx" || additionalExtensions.has(ext) || detectHeadersExport(analysisSource);
 		pages.push({
 			absolutePath: abs,
 			relativePath: rel,
@@ -387,7 +416,8 @@ function scan(dir, root, pages, pageExtensions, shellExtensions, additionalExten
 			revalidateSeconds: revalidate.seconds,
 			hasRevalidateExport: revalidate.present,
 			hasLoader,
-			hasHead
+			hasHead,
+			hasHeaders
 		});
 	}
 }
@@ -585,4 +615,4 @@ function generateRoutesFile(pagesDir, outputPath, options) {
 	].join("\n"), "utf-8");
 }
 //#endregion
-export { sortRoutes as a, createRouteStaticPathsHints as c, extensionGlob as d, normalizeAdditionalExtensions as f, scanPagesDirectory as i, DEFAULT_ROUTE_EXTENSIONS as l, generatePagesManifestSource as n, createRouteHeadHints as o, withAdditionalExtensions as p, generateRoutesFile as r, createRouteLoaderHints as s, filePathToRoutePath as t, LEGACY_BARE_ROUTE_EXTENSIONS as u };
+export { sortRoutes as a, createRouteLoaderHints as c, LEGACY_BARE_ROUTE_EXTENSIONS as d, extensionGlob as f, scanPagesDirectory as i, createRouteStaticPathsHints as l, withAdditionalExtensions as m, generatePagesManifestSource as n, createRouteHeadHints as o, normalizeAdditionalExtensions as p, generateRoutesFile as r, createRouteHeadersHints as s, filePathToRoutePath as t, DEFAULT_ROUTE_EXTENSIONS as u };

package/dist/pages-router.d.mts

@@ -12,6 +12,7 @@ interface ScannedPage {
   hasRevalidateExport?: boolean;
   hasLoader?: boolean;
   hasHead?: boolean;
+  hasHeaders?: boolean;
 }
 interface PagesRouterOptions {
   pagesDir: string;

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-KcCRkhnf.mjs";
+import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-MA9rOl88.mjs";
 export { filePathToRoutePath, generatePagesManifestSource, generateRoutesFile, scanPagesDirectory, sortRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/vite-plugin",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Vite plugin for Pracht apps with virtual modules, dev SSR, prerendering, route inspection, and multi-adapter builds.",
   "keywords": [
     "pracht",
@@ -46,10 +46,10 @@
     "@preact/preset-vite": "^2.10.5",
     "@prefresh/vite": "^2.0.0",
     "es-module-lexer": "^1.7.0",
-    "@pracht/adapter-node": "0.4.0",
-    "@pracht/capabilities": "0.2.0",
+    "@pracht/adapter-node": "0.4.2",
+    "@pracht/capabilities": "0.3.0",
     "@pracht/preact-ssr-precompile": "0.1.3",
-    "@pracht/core": "0.14.0"
+    "@pracht/core": "0.16.0"
   },
   "peerDependencies": {
     "vite": "^8.0.0"