fuzor 0.4.0 → 0.5.1

package/dist/vite.js

@@ -1,29 +1,284 @@
+import { inlineDocumentAssets } from "./compiler/inline-assets.js";
+import { compileDataDocument } from './compiler/data-document.js';
+import { parseRoutePolicy } from './compiler/route-policy.js';
+import { extractPageScripts, compilePageScript } from "./compiler/page-scripts.js";
+import { compileNativeScript } from "./compiler/native-scripts.js";
+import { compileWorkflows, workflowPlugin } from "./workflow/compiler.js";
+import { assertBrowserViewImport } from "./server-components/environment.js";
+import { replaceClosures } from "./server-components/closures.js";
+import { discoverViewReferences, browserReferencesCode } from "./server-components/references.js";
+import { randomUUID } from "node:crypto";
+import { compileFragment, compiledFragmentsPlugin } from "./server-components/compiler.js";
+import { makeRouteMatches } from "./runtime/route-matches.js";
+import { makeClientRouteMatcher } from "./runtime/client-routes.js";
+import { errorHtml, notFoundHtml } from "./boundaries.js";
+import { applyBaseToLinks, rewriteNavigationLinks } from "./compiler/base-links.js";
+import { normalizeBase, routeKey, serverDataPrefix, serverDataUrl, stripBase, withBase } from "./route-path.js";
+import { escapeAttribute, escapeText, inlineScript, jsonScript } from "./html-escape.js";
+import { applyDocumentMetadata, applyGeneratorMetadata, pageHead, readDocumentHead } from "./compiler/metadata.js";
+import * as Effect from "effect/Effect";
+import { scanIslandModulesEffect } from "./compiler/island-modules.js";
 import { mkdir, readFile, readdir, rmdir, unlink, writeFile } from "node:fs/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import path from "node:path";
-import { createServer } from "vite";
-import { compileProject } from "./compiler/index.js";
+import { build as viteBuild, createServer } from "vite";
+import { describeFindings, findInteractiveConstructs, projectImports } from "./compiler/static-analysis.js";
+import { createRuntimes } from "./runtimes.js";
+import { CompileCache, compilePlatformBlocks, compileProject } from "./compiler/index.js";
 import { compileIslands } from "./compiler/islands.js";
-import { createServerHandler } from "./server.js";
+import { createServerHandler, isServerData } from "./server.js";
+import { findServerModules } from "./compiler/server-modules.js";
+import { findApiRoutes } from "./compiler/api-routes.js";
+import { toWebRequest, writeWebResponse } from "./server/node.js";
+import { routeTypes } from "./runtime/href.js";
+import { writeElectronScaffold } from "./electron.js";
+import { createEnvironmentModuleRuntime, detectViteEnvironmentApi, invalidateEnvironmentModule, normalizeEnvironmentConfiguration } from "./vite-environments.js";
 const virtualId = "virtual:fuzor/client";
+const rendererModules = {
+    "virtual:fuzor/compiler/react": 'export { createElement } from "react"; export { renderToString, renderToStaticMarkup } from "react-dom/server";',
+    "virtual:fuzor/compiler/vue": 'export { createSSRApp } from "vue"; export { renderToString } from "vue/server-renderer";',
+    "virtual:fuzor/compiler/solid": 'export { createComponent } from "solid-js"; export { renderToString, generateHydrationScript } from "solid-js/web";'
+};
 const resolvedVirtualId = `\0${virtualId}`;
 const outletStart = "<!--fuzor:outlet-start-->";
 const outletEnd = "<!--fuzor:outlet-end-->";
-function escapeAttribute(value) {
-    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+function findRoute(project, pathname) {
+    const key = routeKey(pathname);
+    return key === undefined ? undefined : project.routes.find((entry) => entry.path === key);
 }
-function routeContent(project, pathname) {
-    const normalized = pathname === "/" ? "/" : `${pathname.replace(/\/+$/, "")}/`;
-    const route = project.routes.find((entry) => entry.path === normalized);
-    if (!route)
-        throw new Error(`No Fuzor route for ${normalized}`);
-    return route.html;
+function boundaryFor(project, kind, scope) {
+    return project.boundaries?.find(boundary => boundary.kind === kind && boundary.scope === scope);
 }
-function outletFor(project, target, pathname) {
+/** Boundary pages by scope, always including a root page (the author's or Fuzor's default). */
+function boundaryPages(project, kind, fallback) {
+    const pages = new Map();
+    const title = kind === "not-found" ? "Page not found" : "Something went wrong";
+    pages.set("/", { html: fallback, metadata: { title } });
+    for (const boundary of project.boundaries ?? []) {
+        if (boundary.kind === kind)
+            pages.set(boundary.scope, { html: boundary.html, metadata: { title, ...boundary.metadata } });
+    }
+    return pages;
+}
+function paramsAttribute(params) {
+    return params ? ` data-fuzor-params="${escapeAttribute(JSON.stringify(params))}"` : "";
+}
+function routeAttributes(route, base) {
+    return `${paramsAttribute(route.params)}${route.pattern || route.requestPattern ? ` data-fuzor-pattern="${escapeAttribute(route.pattern ?? route.path)}"` : ""}${route.requestPattern ? ` data-fuzor-request-pattern="${escapeAttribute(route.requestPattern)}"` : ""}${route.serverData ? ` data-fuzor-data="${escapeAttribute(serverDataUrl(route.path, base))}"` : ""}`;
+}
+function outletFor(project, target, pathname, fallbacks, mixed = false) {
+    const current = findRoute(project, pathname);
+    if (mixed) {
+        target = current?.policy?.navigation === "spa" ? "spa" : "mpa";
+        if (target === "spa")
+            project = { ...project, routes: project.routes.filter(route => route.policy?.navigation === "spa" && route.policy.spaScope === current?.policy?.spaScope) };
+    }
     if (target !== "spa") {
-        return `<fuzor-router>${routeContent(project, pathname)}</fuzor-router>`;
+        const route = findRoute(project, pathname);
+        if (!route)
+            throw new Error(`No Fuzor route for ${pathname}`);
+        return `<fuzor-router data-fuzor-navigation="document"${routeAttributes(route, fallbacks.base)}>${route.html}</fuzor-router>`;
+    }
+    const initial = findRoute(project, pathname);
+    const outlet = initial
+        ? `<fuzor-router data-fuzor-navigation="spa" data-fuzor-initial-route="${escapeAttribute(initial.path)}"${routeAttributes(initial, fallbacks.base)}>${initial.html}</fuzor-router>`
+        : `<fuzor-router></fuzor-router>`;
+    const templates = project.routes.map((route) => `<template data-fuzor-route="${escapeAttribute(route.path)}"${routeAttributes(route, fallbacks.base)}>${route.html}</template>`).join("\n");
+    // "" holds the shell defaults, because the shared document's head already shows the first page's metadata.
+    const metadata = { "": fallbacks.head, ...Object.fromEntries(project.routes.map(route => [route.path, route.metadata ?? {}])) };
+    const boundaries = [];
+    for (const [kind, fallback] of [["not-found", fallbacks.notFound], ["error", fallbacks.error]]) {
+        for (const [scope, page] of boundaryPages(project, kind, fallback)) {
+            boundaries.push(`<template data-fuzor-${kind}="${escapeAttribute(scope)}">${page.html}</template>`);
+            metadata[`${kind}:${scope}`] = page.metadata;
+        }
+    }
+    const redirects = project.redirects ? `\n<script type="application/json" data-fuzor-redirects>${jsonScript(project.redirects)}</script>` : "";
+    return `${outlet}\n${templates}\n${boundaries.join("\n")}\n<script type="application/json" data-fuzor-metadata>${jsonScript(metadata)}</script>${redirects}`;
+}
+/** Bundle the parser-time selector without the asynchronous application runtime. */
+async function inlineInitialRouteScript(options) {
+    const source = fileURLToPath(new URL(`./runtime/initial-route.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`, import.meta.url));
+    const result = await viteBuild({
+        configFile: false, publicDir: false, logLevel: "silent",
+        build: { write: false, minify: true, lib: { entry: source, name: "fuzorInitial", formats: ["iife"] } }
+    });
+    const output = (Array.isArray(result) ? result[0] : result);
+    const code = output.output.find(item => item.type === "chunk")?.code;
+    if (!code)
+        throw new Error("Fuzor initial route selector could not be bundled");
+    return `<script>${inlineScript(`(()=>{${code}\nfuzorInitial.selectInitialRoute(window,${jsonScript(options)});})();`)}</script>`;
+}
+/** Finished documents for a server: nothing is assembled per request. */
+/** Island names in a document: hosts and `client:none` markers. */
+export function documentIslands(html) {
+    const names = new Set();
+    for (const match of html.matchAll(/<fuzor-island\b[^>]*?\ssrc="([^"]+)"/g))
+        names.add(match[1]);
+    for (const match of html.matchAll(/<!--fuzor:static ([^\s]+?)-->/g))
+        names.add(match[1]);
+    return names;
+}
+/**
+ * Links the stylesheets of every island in a document, so prerendered previews and client:none components are
+ * styled at first paint instead of when their JavaScript loads. Links from a template are replaced, not added to.
+ */
+export function withIslandStyles(html, styles, base) {
+    const stripped = html.replace(/<link rel="stylesheet" href="[^"]*" data-fuzor-island-css>/g, "");
+    const files = [...new Set([...documentIslands(stripped)].flatMap(name => styles[name] ?? styles["island:" + name] ?? []))]
+        .map(file => `${base.endsWith("/") ? base : `${base}/`}${file}`)
+        .filter(href => !stripped.includes(`href="${href}"`));
+    if (!files.length)
+        return stripped;
+    return stripped.replace("</head>", () => `${files.map(href => `<link rel="stylesheet" href="${escapeAttribute(href)}" data-fuzor-island-css>`).join("")}</head>`);
+}
+function serverManifest(project, target, template, base, fallbacks, finish = html => html, clientRoutes, assetDirectory, mixed = false) {
+    const boundaryDocuments = (kind, fallback) => Object.fromEntries([...boundaryPages(project, kind, fallback)].map(([scope, page]) => [scope, finish(applyDocumentMetadata(replaceOutlet(template, `<fuzor-router data-fuzor-${kind}="${escapeAttribute(scope)}">${page.html}</fuzor-router>`), pageHead(fallbacks.head, page.metadata)))]));
+    const notFoundDocuments = boundaryDocuments("not-found", fallbacks.notFound);
+    const revalidate = Object.fromEntries(project.routes.flatMap(route => route.metadata?.revalidate === undefined ? [] : [[route.path, route.metadata.revalidate]]));
+    const shared = {
+        ...(Object.keys(revalidate).length ? { revalidate } : {}),
+        ...(project.redirects ? { redirects: project.redirects } : {}),
+        requestPatterns: Object.fromEntries(project.routes.filter(route => route.requestPattern).map(route => [route.requestPattern, route.path])),
+        routePolicies: Object.fromEntries(project.routes.map(route => [route.path, route.policy ?? { rendering: "static", navigation: target === "spa" ? "spa" : "document" }])),
+        notFoundDocument: notFoundDocuments["/"],
+        ...(Object.keys(notFoundDocuments).length > 1 ? { notFoundDocuments } : {}),
+        errorDocument: boundaryDocuments("error", fallbacks.error)["/"],
+        ...(base === "/" ? {} : { base })
+    };
+    const manifest = target === "spa"
+        ? { document: finish(template), routeDocuments: Object.fromEntries(project.routes.map(route => [route.path, finish(applyDocumentMetadata(replaceOutlet(template, outletFor(project, "spa", route.path, fallbacks)), pageHead(fallbacks.head, route.metadata ?? {})))])), routes: Object.fromEntries(project.routes.map((route) => [route.path, true])), ...(clientRoutes ? { clientRoutes, ...(assetDirectory ? { assetDirectory } : {}) } : {}), ...shared }
+        : { documents: Object.fromEntries(project.routes.map((route) => [route.path, finish(applyDocumentMetadata(replaceOutlet(template, outletFor(project, "mpa", route.path, fallbacks, mixed)), pageHead(fallbacks.head, route.metadata ?? {})))])), ...shared };
+    const documents = "documents" in manifest ? manifest.documents : manifest.routeDocuments ?? {};
+    return { ...manifest, dataBindings: Object.fromEntries(project.routes.filter(route => route.policy?.rendering === "request").map(route => [route.path, compileDataDocument(documents[route.path])])) };
+}
+/** Loads each page's `server.ts` default export and checks it was declared with `defineServerData`. */
+async function loadRouteDataModules(project, load, root) {
+    const data = {};
+    for (const route of project.routes) {
+        if (!route.serverData)
+            continue;
+        const module = await load(route.serverData);
+        if (!isServerData(module.default)) {
+            throw new Error(`${path.relative(root, route.serverData)} must export default defineServerData(...) from "fuzor/server".`);
+        }
+        data[route.path] = { data: module.default, ...(route.params ? { params: route.params } : {}) };
+    }
+    return data;
+}
+/** Static hosts cannot send 308s from HTML: a refresh document works everywhere, `_redirects` on hosts that read it. */
+function redirectDocument(destination) {
+    const target = escapeAttribute(destination);
+    return `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><title>Redirecting…</title><meta name="robots" content="noindex"><meta http-equiv="refresh" content="0; url=${target}"><link rel="canonical" href="${target}"></head><body><p>This page has moved to <a href="${target}">${escapeText(destination)}</a>.</p></body></html>\n`;
+}
+async function loadApiModules(files, load) {
+    return Promise.all(files.map(async (route) => ({ pattern: route.pattern, segments: route.segments, source: route.relative, module: await load(route.file) })));
+}
+/**
+ * Cloudflare Workers output: static assets serve every prerendered page, `_redirects` and 404 pages, while
+ * only API endpoints and server data run the Worker. Deploy with `wrangler deploy --config <dir>/wrangler.jsonc`.
+ */
+async function writeCloudflareOutput(directory, root, target, base, clientDirectory, requestRoutes, assetReference) {
+    const packageName = await readFile(path.join(root, "package.json"), "utf8").then(text => JSON.parse(text).name, () => undefined);
+    const name = (packageName ?? path.basename(root)).replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63) || "fuzor-app";
+    await mkdir(path.join(directory, "cloudflare"), { recursive: true });
+    await writeFile(path.join(directory, "cloudflare/worker.mjs"), [
+        "// Generated by Fuzor. Static assets answer page requests; this Worker answers API and server data requests.",
+        'import { handler } from "../entry.mjs";',
+        "",
+        "export default {",
+        "  fetch(request) {",
+        "    return handler(request);",
+        "  }",
+        "};",
+        ""
+    ].join("\n"), "utf8");
+    const prefix = base === "/" ? "" : base.slice(0, -1);
+    const config = {
+        $schema: "../node_modules/wrangler/config-schema.json",
+        name,
+        main: "cloudflare/worker.mjs",
+        compatibility_date: "2026-09-01",
+        assets: {
+            directory: assetReference,
+            binding: "ASSETS",
+            not_found_handling: target === "spa" ? "single-page-application" : "404-page",
+            run_worker_first: [...new Set([`${prefix}/api`, `${prefix}/api/*`, `${prefix}/_fuzor/data/*`, `${prefix}/_fuzor/render`, ...requestRoutes.map(route => withBase(route, base)), ...requestRoutes.map(route => withBase(route.replace(/\/$/, ""), base))])]
+        }
+    };
+    await writeFile(path.join(directory, "wrangler.jsonc"), `// Generated by Fuzor on each build; copy it next to your project to customize.\n${JSON.stringify(config, null, 2)}\n`, "utf8");
+    await writeFile(path.join(clientDirectory, ".assetsignore"), ".fuzor-assets.json\n", "utf8");
+}
+/**
+ * Build-time previews and browser hydration must use the same framework version. React ships its server
+ * renderer in react-dom, a separate package, so a version mismatch between react and react-dom is an error.
+ */
+export function checkRendererVersions(root, islands, runtimes = {}) {
+    for (const [key, packages] of Object.entries(runtimes)) {
+        if (!packages.react || !islands.some(island => island.file.includes(`.${key}.`)))
+            continue;
+        if (!packages["react-dom"])
+            throw new Error(`Runtime ${key} maps react but not react-dom; React islands render and hydrate with both.`);
+        checkPair(root, packages.react, packages["react-dom"], key);
     }
-    const templates = project.routes.map((route) => `<template data-fuzor-route="${escapeAttribute(route.path)}">${route.html}</template>`).join("\n");
-    return `<fuzor-router></fuzor-router>\n${templates}`;
+    if (!islands.some(island => /\.react\.[jt]sx$/.test(island.file)))
+        return;
+    checkPair(root, "react", "react-dom");
+}
+function checkPair(root, reactName, domName, runtime) {
+    // Walk node_modules directories like Vite's resolver; NODE_PATH (set by pnpm scripts) must not count.
+    const version = (name) => {
+        for (let directory = path.resolve(root);; directory = path.dirname(directory)) {
+            try {
+                return JSON.parse(readFileSync(path.join(directory, "node_modules", name, "package.json"), "utf8")).version;
+            }
+            catch { }
+            if (path.dirname(directory) === directory)
+                return undefined;
+        }
+    };
+    const react = version(reactName);
+    const dom = version(domName);
+    const label = runtime ? `Runtime ${runtime} islands` : "React islands";
+    if (!react || !dom)
+        throw new Error(`${label} need both ${reactName} and ${domName} installed (found ${reactName} ${react ?? "missing"}, ${domName} ${dom ?? "missing"}).`);
+    if (react !== dom)
+        throw new Error(`${label} render at build time with ${domName} ${dom} and hydrate with ${reactName} ${react}. Install the same version of both packages.`);
+}
+/** Adds Vite's `id`, `loc` and `frame` to compiler errors so the overlay and build output point at the file. */
+async function withViteLocation(error) {
+    const location = error?.location;
+    if (!location || !(error instanceof Error))
+        return error;
+    const extra = { id: location.file };
+    const line = location.line;
+    if (line !== undefined) {
+        extra.loc = { file: location.file, line, column: location.column ?? 1 };
+        const lines = await readFile(location.file, "utf8").then(text => text.split("\n"), () => []);
+        if (lines.length) {
+            const first = Math.max(1, line - 2);
+            extra.frame = lines.slice(first - 1, line + 2).map((text, index) => {
+                const number = first + index;
+                const gutter = `${number === line ? ">" : " "} ${String(number).padStart(String(line + 2).length)} | `;
+                return number === line ? `${gutter}${text}\n${" ".repeat(gutter.length + (location.column ?? 1) - 1)}^` : `${gutter}${text}`;
+            }).join("\n");
+        }
+    }
+    return Object.assign(error, extra);
+}
+function searchIndex(project, option) {
+    if (!option)
+        return undefined;
+    const scope = typeof option === "object" && option.scope ? routeKey(option.scope) ?? "/" : "/";
+    const documents = project.routes.filter(route => route.path.startsWith(scope) && route.search).map(route => ({
+        path: route.path,
+        title: route.metadata?.navTitle ?? route.search.headings[0] ?? route.metadata?.title ?? route.path,
+        headings: route.search.headings.slice(1),
+        text: route.search.text
+    }));
+    return JSON.stringify({ version: 1, documents });
 }
 function replaceOutlet(document, content) {
     const start = document.indexOf(outletStart);
@@ -32,288 +287,1129 @@ function replaceOutlet(document, content) {
         throw new Error(`index.html must contain ${outletStart} and ${outletEnd}.`);
     return document.slice(0, start + outletStart.length) + content + document.slice(end);
 }
-export function fuzorPlugin(options = {}) {
-    const target = options.target ?? process.env.FUZOR_TARGET ?? "spa";
-    if (target !== "spa" && target !== "mpa") {
-        throw new Error(`Unknown Fuzor navigation target: ${target}. Choose spa or mpa.`);
+function serverViewDocument(html) {
+    let found = false;
+    const document = html.replace(/(<fuzor-router\b[^>]*>)[\s\S]*?<\/fuzor-router>/, (_match, open) => { found = true; return open + "<!--fuzor-view--></fuzor-router>"; });
+    if (!found || !document.includes("</body>"))
+        throw new Error("Server views require a compiled outlet and a document body.");
+    return document.replace("</body>", "<!--fuzor-snapshot--></body>");
+}
+/**
+ * The plugin creates private Vite servers to load island and `paths` modules. Their config file loads
+ * this plugin again; those nested instances only provide virtual modules and never compile the project.
+ */
+const nestedServer = new AsyncLocalStorage();
+/**
+ * Vite servers Fuzor starts inside a dev server or build to load pages' modules and analyze islands. They must not
+ * open an HMR WebSocket (two would compete for its port, and a failed one never closes) and must not share the
+ * dev server's dependency cache (each would re-optimize and invalidate the other's pre-bundled files).
+ */
+export function nestedServerConfig(config) {
+    return {
+        root: config.root,
+        configFile: config.configFile ?? false,
+        plugins: [workflowPlugin(), {
+                name: "fuzor:nested-renderers",
+                resolveId(id) { if (Object.hasOwn(rendererModules, id))
+                    return `\0${id}`; },
+                load(id) { if (id.startsWith("\0") && Object.hasOwn(rendererModules, id.slice(1)))
+                    return rendererModules[id.slice(1)]; }
+            }],
+        server: { middlewareMode: true, hmr: false, ws: false },
+        cacheDir: path.join(config.cacheDir, "fuzor-nested"),
+        optimizeDeps: { noDiscovery: true, include: [] },
+        appType: "custom"
+    };
+}
+/**
+ * Resolves the build profile. Sources, highest first: explicit `fuzorPlugin()` options, the `FUZOR_TARGET`,
+ * `FUZOR_SERVER` and `FUZOR_INLINE` environment variables (which the CLI flags set), then defaults
+ * (`spa`, static, not inline). A plugin option and a different environment value is a configuration
+ * error rather than a silent override, because the CLI flag would otherwise be ignored.
+ */
+export function resolveFuzorProfile(options = {}, env = process.env, serverModules = []) {
+    const flag = (name) => {
+        const value = env[name]?.trim().toLowerCase();
+        if (value === undefined || value === "")
+            return undefined;
+        if (value === "1" || value === "true")
+            return true;
+        if (value === "0" || value === "false")
+            return false;
+        throw new Error(`${name} must be 1, 0, true or false; received ${JSON.stringify(env[name])}.`);
+    };
+    if (options.navigation !== undefined && !["auto", "navigation-api", "embedded"].includes(options.navigation)) {
+        throw new Error(`fuzorPlugin({ navigation }) must be "auto", "navigation-api" or "embedded"; received ${JSON.stringify(options.navigation)}.`);
+    }
+    const envTarget = env.FUZOR_TARGET?.trim() || undefined;
+    if (envTarget !== undefined && envTarget !== "spa" && envTarget !== "mpa" && envTarget !== "electron") {
+        throw new Error(`Unknown Fuzor navigation target in FUZOR_TARGET: ${envTarget}. Choose spa, mpa or electron.`);
+    }
+    const envServer = flag("FUZOR_SERVER");
+    const envInline = flag("FUZOR_INLINE");
+    const envElectron = flag("FUZOR_ELECTRON");
+    const envPlatform = env.FUZOR_PLATFORM?.trim() || undefined;
+    const platform = options.platform ?? envPlatform ?? (envTarget === "electron" ? "desktop" : "web");
+    if (!/^[a-z][a-z0-9-]*$/.test(platform))
+        throw new Error(`Invalid Fuzor platform ${JSON.stringify(platform)}. Use lowercase letters, digits and hyphens.`);
+    if (options.platform !== undefined && envPlatform !== undefined && options.platform !== envPlatform) {
+        throw new Error(`fuzorPlugin({ platform: ${JSON.stringify(options.platform)} }) conflicts with FUZOR_PLATFORM=${JSON.stringify(envPlatform)}.`);
+    }
+    const envAdapter = env.FUZOR_ADAPTER?.trim() || undefined;
+    for (const [label, value] of [["fuzorPlugin({ adapter })", options.adapter], ["FUZOR_ADAPTER", envAdapter]]) {
+        if (value !== undefined && value !== "node" && value !== "cloudflare")
+            throw new Error(`Unknown Fuzor adapter in ${label}: ${value}. Choose node or cloudflare.`);
+    }
+    if (options.adapter !== undefined && envAdapter !== undefined && options.adapter !== envAdapter) {
+        throw new Error(`fuzorPlugin({ adapter: ${JSON.stringify(options.adapter)} }) conflicts with FUZOR_ADAPTER=${JSON.stringify(envAdapter)} (set by a CLI flag or the environment). Remove one of them.`);
     }
-    const withServer = options.server ?? process.env.FUZOR_SERVER === "1";
-    const inline = options.inline ?? process.env.FUZOR_INLINE === "1";
-    if (inline && withServer)
+    const adapter = (options.adapter ?? envAdapter ?? "node");
+    const conflict = (option, optionValue, variable, envValue) => {
+        if (optionValue !== undefined && envValue !== undefined && optionValue !== envValue) {
+            throw new Error(`fuzorPlugin({ ${option}: ${JSON.stringify(optionValue)} }) conflicts with ${variable}=${JSON.stringify(envValue)} (set by a CLI flag or the environment). Remove one of them.`);
+        }
+    };
+    // The CLI always states server/inline explicitly; only an enabled flag can contradict a plugin option.
+    if (envServer)
+        conflict("server", options.server, "FUZOR_SERVER", envServer);
+    if (envInline)
+        conflict("inline", options.inline, "FUZOR_INLINE", envInline);
+    const packaged = ["desktop", "ios", "android"].includes(platform);
+    const requestedTarget = envTarget ?? (envInline || options.inline || packaged ? "spa" : "mpa");
+    const mixed = envTarget === undefined && !envInline && !options.inline && !packaged;
+    const electron = options.electron ?? envElectron ?? requestedTarget === "electron";
+    const target = (requestedTarget === "electron" ? "spa" : requestedTarget);
+    const serverReasons = serverModules.map(file => file.startsWith("api/") ? `${file} defines an API endpoint` : file.endsWith(".html") ? `${file} declares request rendering` : `${file} defines server data`);
+    if (options.serverComponents) {
+        makeClientRouteMatcher(Object.fromEntries(options.serverComponents.routes.map(route => [route, "/"])));
+        for (const entry of [options.serverComponents.server, options.serverComponents.client, options.serverComponents.references].filter((value) => value !== undefined)) {
+            if (!entry || path.isAbsolute(entry) || entry.split(/[\\/]/).includes(".."))
+                throw new Error("Server component entries must be paths inside the project.");
+        }
+        if (!options.serverComponents.client && !options.serverComponents.references)
+            throw new Error("Server components require a client entry or generated reference directory.");
+        if (!options.serverComponents.routes.length)
+            throw new Error("Server components need at least one route.");
+        if (options.navigation === "embedded")
+            throw new Error("Server components require HTTP navigation.");
+        serverReasons.push(`${options.serverComponents.server} defines server components`);
+    }
+    const inline = electron || packaged ? true : options.inline ?? envInline ?? false;
+    if (inline && target !== "spa")
+        throw new Error("Inline output is only supported for the SPA target.");
+    if (electron && target !== "spa")
+        throw new Error("Electron output is only supported for the SPA target.");
+    if (serverReasons.length) {
+        const needs = `This app needs server output because ${serverReasons.join("; ")}.`;
+        if (inline)
+            throw new Error(`${needs} Inline SPA output is a static single file and cannot answer data requests; remove --inline.`);
+        if (options.server === false)
+            throw new Error(`${needs} Remove server: false from fuzorPlugin().`);
+        if (envServer === false)
+            throw new Error(`${needs} Unset FUZOR_SERVER=0.`);
+    }
+    if (adapter === "cloudflare" && inline)
+        throw new Error("The cloudflare adapter builds a Worker and cannot be combined with inline output.");
+    if (adapter === "cloudflare" && options.server === false)
+        throw new Error("The cloudflare adapter implies server output; remove server: false.");
+    const server = serverReasons.length > 0 || adapter === "cloudflare" || (options.server ?? envServer ?? false);
+    if (inline && server)
         throw new Error("SPA inline output cannot be combined with server output.");
-    const serverOutDir = `dist-${target}-server/client`;
+    return { target, mixed, backendOutDir: ".fuzor/dist-backend", platform, server, inline, outDir: electron ? ".fuzor/dist-desktop" : platform !== "web" ? `.fuzor/dist-${platform}` : mixed ? ".fuzor/web/dist" : `.fuzor/web/dist-${target}`, serverReasons, adapter, ...(electron ? { electron: true } : {}) };
+}
+export function fuzorPlugin(options = {}) {
+    const nested = nestedServer.getStore() === true;
+    let viewBuildId = randomUUID();
+    let referencesPromise;
+    const references = () => referencesPromise ??= discoverViewReferences(vite.root, options.serverComponents.references);
+    const referenceStub = (file, refs) => {
+        const relative = path.relative(vite.root, file).split(path.sep).join("/");
+        const client = refs.clients.find(ref => ref.file === relative);
+        if (client)
+            return `export default ${JSON.stringify({ id: client.id })};`;
+        const closures = refs.closures.filter(ref => ref.file === relative);
+        if (closures.length)
+            return readFile(file, "utf8").then(code => replaceClosures(code, closures));
+        const handlers = refs.handlers.filter(ref => ref.file === relative);
+        return handlers.length ? handlers.map(ref => `export const ${ref.name}=${JSON.stringify({ id: ref.id })};`).join("\n") : undefined;
+    };
+    const generatedViews = async (views) => {
+        if (!options.serverComponents?.references)
+            return views;
+        const refs = await references();
+        return { ...views, manifest: { buildId: viewBuildId, templates: refs.templates }, components: refs.clients.map(ref => ref.id), handlers: [...refs.handlers.map(ref => ref.id), ...refs.closures.map(ref => ref.id)] };
+    };
+    const configuredEnvironments = normalizeEnvironmentConfiguration(options.experimental?.environments);
+    const environmentNames = {
+        client: configuredEnvironments.client ?? "client",
+        server: configuredEnvironments.server ?? "server",
+        edge: configuredEnvironments.edge ?? "edge"
+    };
+    const environmentApiEnabled = Object.keys(configuredEnvironments).length > 0;
+    const moduleEnvironment = options.experimental?.runtime === "edge" ? environmentNames.edge : environmentNames.server;
+    // Validated immediately for early errors; server data detection refines it once the root is known.
+    let profile = resolveFuzorProfile(options);
+    let { target, inline } = profile;
+    let withServer = profile.server;
+    let serverModuleFiles = [];
+    let apiFiles = [];
+    /**
+     * Development CSS arrives through module imports; client:none components have none, so documents import them
+     * for their styles. Production builds link the extracted stylesheets instead.
+     */
+    const withStaticModuleImports = (html) => {
+        const withoutPrevious = html.replace(/<script type="module" data-fuzor-static-css>.*?<\/script>/g, "");
+        const files = [...withoutPrevious.matchAll(/<!--fuzor:static ([^\s]+?)-->/g)].flatMap(match => islands.filter(island => island.name === match[1]).map(island => island.file));
+        return files.length ? withoutPrevious.replace("</head>", () => `<script type="module" data-fuzor-static-css>${[...new Set(files)].map(file => `import ${JSON.stringify(file)};`).join("")}</script></head>`) : withoutPrevious;
+    };
+    let buildFailed = false;
+    /** Stylesheets each island loads, from the client bundle. */
+    let islandStyles = {};
+    let bundleWritten = false;
     let vite;
+    let environmentCapability = { supported: false, reason: "legacy" };
+    const environmentState = new Map();
+    let releaseRuntimeHooks = () => { };
+    let runtimes;
+    /** Runtime copies of framework adapters and renderers, by resolved module ID. */
+    const runtimeModules = new Map();
+    /** Path deployment base from Vite's `base`; relative and absolute-URL bases leave routes at `/`. */
+    let pathBase = "/";
+    /** The shell's own head, read before any page metadata is applied to it. */
+    let shellHead = {};
+    const fallbacks = () => ({ notFound: applyBaseToLinks(notFoundHtml, pathBase), error: applyBaseToLinks(errorHtml, pathBase), base: pathBase, head: shellHead });
     let project;
+    let pageScripts = [];
+    const nativeHandlers = new Map();
+    let inlineModuleFiles = [];
+    let scriptRoutes = [];
+    const routeScriptId = (route) => `virtual:fuzor/route-client/${encodeURIComponent(route.path)}/${route.path === "/" ? "index" : route.path.split("/").filter(Boolean).join("-").replace(/[^a-zA-Z0-9_-]/g, "_")}-client.js`;
+    const pageScriptId = (script) => `virtual:fuzor/page-script/${script.id}.js`;
+    let revision = 0;
+    let compilation;
     let projectPromise;
-    let rawProject;
     let devServer;
-    let needsSolidHydration = false;
+    let hydrationScript = "";
     let islands = [];
     const loadProject = async () => {
         if (project)
             return project;
         if (projectPromise)
             return projectPromise;
-        projectPromise = (async () => {
-            const raw = rawProject ?? await compileProject(vite.root);
-            if (islands.length === 0)
-                return project = raw;
-            const ownedServer = devServer ? undefined : await createServer({
-                root: vite.root,
-                configFile: vite.configFile ?? false,
-                server: { middlewareMode: true, hmr: false },
-                optimizeDeps: { noDiscovery: true, include: [] },
-                appType: "custom"
-            });
-            const server = devServer ?? ownedServer;
-            const modules = new Map();
+        const version = revision;
+        const lifetime = new AbortController();
+        compilation = lifetime;
+        const registry = islands;
+        let solidHydrationScript = "";
+        const pending = (async () => {
+            let owned;
+            const createModuleServer = () => nestedServer.run(true, () => createServer(nestedServerConfig(vite)));
+            const moduleServer = () => devServer ? Promise.resolve(devServer) : owned ??= createModuleServer();
+            // client:none analysis reads client transforms without HMR code, which the dev server would add. It has its
+            // own server: client transforms wait for pending requests to settle, and preview renders on the module
+            // server are waiting for this analysis.
+            let ownedAnalysis;
+            const analysisServer = () => ownedAnalysis ??= createModuleServer();
+            const analyzed = new Map();
+            const analyze = (entry) => {
+                let pending = analyzed.get(entry);
+                if (!pending) {
+                    pending = (async () => {
+                        const server = await analysisServer();
+                        const { parseAstAsync } = await import("vite");
+                        const findings = [];
+                        const seen = new Set();
+                        const queue = [entry];
+                        while (queue.length) {
+                            const url = queue.shift();
+                            if (seen.has(url))
+                                continue;
+                            seen.add(url);
+                            const result = await server.transformRequest(url);
+                            if (!result)
+                                continue;
+                            const program = await parseAstAsync(result.code);
+                            findings.push(...findInteractiveConstructs(program, path.join(vite.root, url.split("?")[0])));
+                            queue.push(...projectImports(program));
+                        }
+                        return findings;
+                    })();
+                    analyzed.set(entry, pending);
+                }
+                return pending;
+            };
             try {
-                return project = await compileIslands(raw, async (name, props, id) => {
-                    const island = islands.find((entry) => entry.name === name);
+                const raw = await compileRaw(lifetime.signal, async (file) => createEnvironmentModuleRuntime(await moduleServer(), moduleEnvironment, environmentApiEnabled).loadModule(file));
+                if (registry.length === 0) {
+                    const missing = async (name) => { throw new Error(`Unknown Fuzor component: ${name}`); };
+                    return await compileIslands(raw, missing, { signal: lifetime.signal });
+                }
+                const server = await moduleServer();
+                const modules = new Map();
+                const renderer = async (name, props, id, mode) => {
+                    const island = registry.find((entry) => entry.name === name);
                     if (!island)
                         throw new Error(`Unknown Fuzor island: ${name}`);
-                    let loaded = modules.get(name);
+                    const key = name;
+                    let loaded = modules.get(key);
                     if (!loaded) {
-                        loaded = server.ssrLoadModule(island.file);
-                        modules.set(name, loaded);
+                        loaded = createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule(island.file);
+                        modules.set(key, loaded);
                     }
                     const module = await loaded;
+                    const staticMount = module.mount;
+                    if (mode === "static") {
+                        if (staticMount && !staticMount.framework) {
+                            throw new Error(`${island.file} exports mount(), which client:none never runs. Remove mount() for a build-only component, or use another client: directive.`);
+                        }
+                        if (island.file.endsWith(".vue") || staticMount?.framework) {
+                            const findings = await analyze(island.file);
+                            if (findings.length)
+                                throw new Error(`client:none would drop behavior of ${island.file}. It uses:\n${describeFindings(findings, vite.root)}\nUse client:load, client:idle, client:visible or client:interaction instead.`);
+                        }
+                    }
                     if (island.file.endsWith(".vue")) {
-                        const [{ createSSRApp }, { renderToString }] = await Promise.all([import("vue"), import("vue/server-renderer")]);
+                        const load = createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule;
+                        const { createSSRApp, renderToString } = await load("virtual:fuzor/compiler/vue");
                         return renderToString(createSSRApp(module.default, props));
                     }
                     const mount = module.mount;
                     if (mount?.framework === "react" && mount.component) {
-                        const [{ createElement }, { renderToString }] = await Promise.all([import("react"), import("react-dom/server")]);
-                        return renderToString(createElement(mount.component, props), { identifierPrefix: `fuzor-${id}-` });
+                        const runtime = runtimes?.scopeOf(island.file)?.key;
+                        const rendererId = runtime ? `virtual:fuzor/compiler/react@${runtime}` : "virtual:fuzor/compiler/react";
+                        const load = createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule;
+                        const { createElement, renderToString } = await load(rendererId);
+                        if (mode === "static") {
+                            const { renderToStaticMarkup } = await load(rendererId);
+                            return renderToStaticMarkup(createElement(mount.component, props));
+                        }
+                        const tree = mount.element ? mount.element(props) : createElement(mount.component, props);
+                        return renderToString(tree, { identifierPrefix: `fuzor-${id}-` });
                     }
                     if (mount?.framework === "solid" && mount.component) {
-                        const [{ createComponent }, { renderToString }] = await Promise.all([import("solid-js"), import("solid-js/web")]);
-                        needsSolidHydration = true;
-                        return renderToString(() => createComponent(mount.component, props), { renderId: id });
+                        const solidRuntime = runtimes?.scopeOf(island.file)?.key;
+                        const load = createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule;
+                        const { createComponent, renderToString, generateHydrationScript } = await load(solidRuntime ? `virtual:fuzor/compiler/solid@${solidRuntime}` : "virtual:fuzor/compiler/solid");
+                        if (mode === "hydrate")
+                            solidHydrationScript = generateHydrationScript();
+                        const html = renderToString(() => createComponent(mount.component, props), { renderId: id });
+                        // Hydration keys only matter to Solid's client, which a client:none component never loads.
+                        return mode === "static" ? html.replace(/ data-hk="[^"]*"/g, "") : html;
+                    }
+                    // Public adapter contract: any island module may render its preview at build time.
+                    if (typeof module.render === "function") {
+                        const html = await module.render(props, { id });
+                        if (typeof html !== "string")
+                            throw new Error(`${island.file}: render() must return a string or a promise of one.`);
+                        return html;
                     }
-                    if (typeof module.render === "function")
-                        return module.render(props);
                     return undefined;
-                });
+                };
+                return await compileIslands(raw, renderer, { signal: lifetime.signal });
             }
             finally {
-                await ownedServer?.close();
+                if (owned)
+                    await (await owned).close();
+                if (ownedAnalysis) {
+                    const analysis = await ownedAnalysis;
+                    // Client transforms can start dependency pre-bundling (Solid's plugin adds entries); closing before it
+                    // settles leaves esbuild's service referenced and the build process never exits.
+                    const client = analysis.environments?.client;
+                    await client?.waitForRequestsIdle?.();
+                    await client?.depsOptimizer?.scanProcessing;
+                    await analysis.close();
+                }
             }
         })();
+        const published = pending.then(result => {
+            if (version !== revision)
+                return loadProject();
+            hydrationScript = solidHydrationScript;
+            if (options.routeTypes !== false)
+                void writeRouteTypes(result).catch(error => vite.logger?.warn(`[fuzor] Could not write .fuzor/routes.d.ts: ${String(error)}`));
+            project = pathBase === "/" ? result : { ...result,
+                routes: result.routes.map(route => ({ ...route, html: applyBaseToLinks(route.html, pathBase) })),
+                ...(result.boundaries ? { boundaries: result.boundaries.map(boundary => ({ ...boundary, html: applyBaseToLinks(boundary.html, pathBase) })) } : {}) };
+            return project;
+        }, error => {
+            if (version !== revision)
+                return loadProject();
+            throw error;
+        });
+        projectPromise = published;
         try {
-            return await projectPromise;
+            return await published;
         }
         finally {
-            projectPromise = undefined;
+            if (projectPromise === published)
+                projectPromise = undefined;
+            if (compilation === lifetime)
+                compilation = undefined;
         }
     };
-    const scanIslands = async () => {
-        const islandDir = path.join(vite.root, "islands");
-        try {
-            const entries = await readdir(islandDir, { withFileTypes: true });
-            islands = entries
-                .filter((entry) => entry.isFile() && /\.(ts|tsx|js|jsx|vue)$/.test(entry.name))
-                .map((entry) => ({ name: entry.name.replace(/(?:\.(?:react|solid))?\.(ts|tsx|js|jsx|vue)$/, ""), file: `/islands/${entry.name}` }));
-            const names = new Set();
-            for (const island of islands) {
-                if (names.has(island.name))
-                    throw new Error(`Duplicate Fuzor island name: ${island.name}`);
-                names.add(island.name);
-            }
+    // Dev servers recompile on every change; unchanged pages come from here.
+    const compileCache = new CompileCache();
+    let writtenTypes = "";
+    const writeRouteTypes = async (compiled) => {
+        const file = path.join(vite.root, ".fuzor/routes.d.ts");
+        // Import specifiers use .js, which TypeScript maps to the .ts source under Bundler and NodeNext resolution.
+        const moduleSpecifier = (source) => {
+            const relative = path.relative(path.dirname(file), source).split(path.sep).join("/").replace(/\.ts$/, ".js").replace(/\.mts$/, ".mjs");
+            return relative.startsWith(".") ? relative : `./${relative}`;
+        };
+        const content = routeTypes([
+            ...compiled.routes.map(route => ({ pattern: route.pattern ?? route.path, ...(route.paramsSchema ? { paramsModule: moduleSpecifier(route.paramsSchema) } : {}) })),
+            ...apiFiles.map(route => route.pattern)
+        ]);
+        if (content === writtenTypes)
+            return;
+        if (await readFile(file, "utf8").catch(() => "") !== content) {
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, content, "utf8");
         }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
-            islands = [];
+        writtenTypes = content;
+    };
+    const compileRaw = async (signal, loadModule) => {
+        let compiled = await compileProject(vite.root, { ...(options.markdown ? { markdown: options.markdown } : {}), ...(options.redirects ? { redirects: options.redirects } : {}), platform: profile.platform, signal, loadModule, cache: compileCache })
+            .catch(async (error) => { throw await withViteLocation(error); });
+        const entry = options.entry ?? process.env.FUZOR_ENTRY;
+        if (entry) {
+            if (!inline || target !== "spa")
+                throw new Error("An application entry requires an inline SPA build.");
+            const scope = routeKey(entry);
+            const rootRoute = compiled.routes.find(route => route.path === scope);
+            if (!scope || !rootRoute || rootRoute.policy?.navigation !== "spa")
+                throw new Error("Application entry must name a declared SPA boundary.");
+            const selected = compiled.routes.filter(route => route.path.startsWith(scope) && route.policy?.navigation === "spa" && route.policy.rendering === "static");
+            if (selected.some(route => route.serverData))
+                throw new Error("Inline application entries cannot use same-origin server-data endpoints. Use an explicitly hosted backend API in client code, or an HTTP rendering deployment.");
+            const rebase = (value) => scope === "/" || !value.startsWith(scope) ? value : "/" + value.slice(scope.length);
+            compiled = { ...compiled, routes: selected.map(route => ({ ...route, path: rebase(route.path), html: rewriteNavigationLinks(route.html, rebase), policy: { ...route.policy, spaScope: rebase(route.policy.spaScope ?? scope) } })), boundaries: [], redirects: {} };
+            if (!compiled.routes.some(route => route.path === "/"))
+                throw new Error("Application entry must have a static root template; request-rendered routes require an HTTP rendering deployment.");
+        }
+        const deployment = options.deployment ?? process.env.FUZOR_DEPLOYMENT;
+        const requestRoutes = compiled.routes.filter(route => route.policy?.rendering === "request");
+        if (deployment && !["static", "github-pages", "node", "cloudflare"].includes(deployment))
+            throw new Error("Unknown Fuzor deployment target: " + deployment);
+        if ((deployment === "static" || deployment === "github-pages") && (requestRoutes.length || options.serverComponents?.routes.length))
+            throw new Error(`Route ${(requestRoutes[0]?.path ?? options.serverComponents.routes[0])} requires request-time server rendering. ${deployment} supports static files only. Pre-render this route, regenerate and republish its files, or choose node/cloudflare rendering. Remote API calls from static SPAs are allowed.`);
+        for (const route of requestRoutes)
+            if (route.requestPattern && route.policy?.navigation === "spa" && !options.serverComponents?.routes.some(pattern => makeClientRouteMatcher({ [pattern]: "/" })(route.path)))
+                throw new Error(`${route.source}: unenumerated request routes inside an SPA require a server-component renderer. Use navigation=document or register serverComponents.`);
+        if (options.routeTree) {
+            if (target !== "spa" && !profile.mixed)
+                throw new Error("routeTree requires a SPA target.");
+            makeRouteMatches(options.routeTree);
+            const check = (value, seen = new Set()) => {
+                if (value === undefined || value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
+                    return;
+                if (typeof value !== "object" || seen.has(value))
+                    throw new Error("routeTree handles must be serializable JSON data.");
+                if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+                    throw new Error("routeTree handles must be serializable JSON data.");
+                seen.add(value);
+                for (const child of Object.values(value))
+                    check(child, seen);
+                seen.delete(value);
+            };
+            check(options.routeTree);
         }
+        if (options.clientRoutes && Object.keys(options.clientRoutes).length) {
+            if (target !== "spa" || !options.serverComponents && (withServer || apiFiles.length > 0 || serverModuleFiles.length > 0))
+                throw new Error("clientRoutes requires a static SPA target.");
+            makeClientRouteMatcher(options.clientRoutes);
+            for (const target of Object.values(options.clientRoutes)) {
+                const route = compiled.routes.find(route => route.path === routeKey(target));
+                if (!route)
+                    throw new Error(`Client route template ${target} is not compiled.`);
+                if (route.serverData)
+                    throw new Error("Client route templates cannot have server data.");
+            }
+        }
+        for (const warning of compiled.warnings ?? [])
+            vite.logger.warn(`[fuzor] ${warning}`);
+        const shadowed = apiFiles.length ? compiled.routes.find(route => route.path === "/api/" || route.path.startsWith("/api/")) : undefined;
+        if (shadowed)
+            throw new Error(`${path.relative(vite.root, shadowed.source)} is below /api/, which belongs to the api/ folder. Move the page.`);
+        const extracted = extractPageScripts(compiled, vite.root);
+        pageScripts = extracted.scripts;
+        scriptRoutes = extracted.routes;
+        return extracted.project;
+    };
+    const scanIslands = async () => {
+        return Effect.runPromise(scanIslandModulesEffect(vite.root, Object.keys(options.runtimes ?? {})));
     };
     const refresh = async (server) => {
+        const version = ++revision;
+        viewBuildId = randomUUID();
+        referencesPromise = undefined;
+        compilation?.abort();
         project = undefined;
-        rawProject = undefined;
         projectPromise = undefined;
-        needsSolidHydration = false;
-        await scanIslands();
+        hydrationScript = "";
+        const nextApi = findApiRoutes(vite.root);
+        const nextModules = (options.entry ?? process.env.FUZOR_ENTRY) && inline ? [] : [...findServerModules(vite.root), ...nextApi.map(route => route.relative)];
+        const nextProfile = resolveFuzorProfile(options, process.env, nextModules);
+        apiFiles = nextApi;
+        serverModuleFiles = nextModules;
+        profile = nextProfile;
+        withServer = profile.server;
+        const nextIslands = await scanIslands();
+        if (version !== revision)
+            return;
+        islands = nextIslands;
         await loadProject();
-        const module = server.moduleGraph.getModuleById(resolvedVirtualId);
-        if (module)
-            server.moduleGraph.invalidateModule(module);
+        if (version !== revision)
+            return;
+        invalidateEnvironmentModule(server, resolvedVirtualId, environmentNames.client, environmentApiEnabled);
+        environmentState.set(environmentNames.server, { revision, ...(project ? { project } : {}) });
         server.ws.send({ type: "full-reload" });
     };
     return {
         name: "fuzor",
         enforce: "pre",
-        config() {
-            if (withServer)
-                return { build: { outDir: serverOutDir } };
-            if (target === "spa" && inline)
-                return {
-                    build: {
-                        cssCodeSplit: false,
-                        assetsInlineLimit: Number.MAX_SAFE_INTEGER,
-                        rollupOptions: { output: { inlineDynamicImports: true } }
-                    }
-                };
+        api: {
+            profile: () => profile,
+            project: () => loadProject(),
+            apiRoutes: () => apiFiles.map(route => ({ pattern: route.pattern, source: route.relative })),
+            environments: () => ({ ...environmentNames }),
+            environmentApi: () => environmentCapability
+        },
+        async config(config) {
+            const projectRoot = path.resolve(config.root ?? process.cwd());
+            runtimes = createRuntimes(projectRoot, options.runtimes);
+            // Dependency pre-bundling resolves imports inside aliased packages with its own bundler.
+            const viteModule = runtimes.enabled ? await import("vite") : {};
+            const runtimeOptimizer = runtimes.enabled ? (() => {
+                const active = runtimes;
+                const rootFile = path.join(projectRoot, "package.json");
+                // Vite 8 bundles dependencies with Rolldown and exports its version; earlier majors use esbuild.
+                if ("rolldownVersion" in viteModule) {
+                    return { rolldownOptions: { plugins: [{ name: "fuzor:runtimes", async resolveId(source, importer) {
+                                        const runtime = importer ? active.packageScope(importer) : undefined;
+                                        const mapped = runtime && active.mapSpecifier(runtime, source);
+                                        return mapped ? this.resolve(mapped, rootFile, { skipSelf: true }) : null;
+                                    } }] } };
+                }
+                return { esbuildOptions: { plugins: [{ name: "fuzor:runtimes", setup(build) {
+                                    build.onResolve({ filter: /^[\w@]/ }, async (args) => {
+                                        const runtime = args.importer ? active.packageScope(args.importer) : undefined;
+                                        const mapped = runtime && active.mapSpecifier(runtime, args.path);
+                                        if (!mapped)
+                                            return undefined;
+                                        const result = await build.resolve(mapped, { kind: args.kind, resolveDir: projectRoot });
+                                        return result.errors.length ? { errors: result.errors } : { path: result.path, external: result.external, namespace: result.namespace };
+                                    });
+                                } }] } };
+            })() : {};
+            if (nested)
+                return { resolve: { dedupe: ["react", "react-dom", "solid-js", "vue"] }, ...(runtimes.enabled ? { optimizeDeps: runtimeOptimizer } : {}) };
+            apiFiles = findApiRoutes(path.resolve(config.root ?? process.cwd()));
+            serverModuleFiles = (options.entry ?? process.env.FUZOR_ENTRY) && inline ? [] : [...findServerModules(path.resolve(config.root ?? process.cwd())), ...apiFiles.map(route => route.relative)];
+            profile = resolveFuzorProfile(options, process.env, serverModuleFiles);
+            ({ target, inline } = profile);
+            withServer = profile.server;
+            if (options.clientRoutes && Object.keys(options.clientRoutes).length && (target !== "spa" || withServer && !options.serverComponents))
+                throw new Error("clientRoutes requires a static SPA target.");
+            const packageJson = await readFile(path.join(path.resolve(config.root ?? process.cwd()), "package.json"), "utf8").then(text => JSON.parse(text), () => ({}));
+            const dependencies = { ...packageJson.dependencies, ...packageJson.devDependencies };
+            const include = ["Cause", "Context", "Deferred", "Effect", "Exit", "Fiber", "Layer", "Schema", "Scope", "reactivity/Atom", "reactivity/AtomRegistry"].map(module => `fuzor > effect/${module}`);
+            if (dependencies.react && dependencies["react-dom"])
+                include.push("react", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime");
+            if (dependencies.vue)
+                include.push("vue");
+            return {
+                resolve: { dedupe: ["react", "react-dom", "solid-js", "vue"] },
+                // A `*.fragment.html` is a compiled fragment, not a page: Vite's dependency scan would load it as an entry and
+                // fail on the virtual module it resolves to. Pages keep Vite's own default of every `.html` file.
+                optimizeDeps: { include, ...(config.optimizeDeps?.entries === undefined ? { entries: ["**/*.html", "!**/*.fragment.html"] } : {}), ...runtimeOptimizer },
+                // Vite 6.4 accepts named environments in the config hook. This is
+                // emitted only for explicit opt-in; Vite 6/7 legacy users are untouched.
+                ...(options.experimental?.environments ? {
+                    environments: Object.fromEntries(Object.values(environmentNames).filter(name => name !== "client").map(name => [name, { consumer: "server" }]))
+                } : {}),
+                build: {
+                    ...(config.build?.outDir === undefined ? { outDir: process.env.FUZOR_STAGE_DIR ? path.join(process.env.FUZOR_STAGE_DIR, profile.outDir) : profile.outDir } : {}),
+                    ...(target === "spa" && inline ? { cssCodeSplit: false, modulePreload: false, assetsInlineLimit: Number.MAX_SAFE_INTEGER } : {})
+                }
+            };
         },
         async configResolved(config) {
             vite = config;
-            rawProject = await compileProject(config.root);
-            await scanIslands();
+            environmentCapability = detectViteEnvironmentApi({ config });
+            pathBase = normalizeBase(config.base);
+            if (nested)
+                return;
+            islands = await scanIslands();
+            checkRendererVersions(config.root, islands, options.runtimes);
+            if (runtimes?.enabled) {
+                const vueRuntime = islands.find(island => island.file.endsWith(".vue") && runtimes.scopeOf(island.file));
+                if (vueRuntime)
+                    throw new Error(`${vueRuntime.file}: runtimes support JSX islands only. Vue's compiler adds its own imports of vue, which Fuzor cannot redirect.`);
+            }
         },
-        resolveId(id) {
-            return id === virtualId ? resolvedVirtualId : undefined;
+        async resolveId(id, importer, resolveOptions) {
+            if (!resolveOptions.ssr)
+                assertBrowserViewImport(id, importer);
+            if (id === "fuzor/server-components/server" && !resolveOptions.ssr) {
+                throw new Error("The server-component evaluator is server-only. Import browser runtime and protocol separately.");
+            }
+            if (id.startsWith("virtual:fuzor/route-client/"))
+                return `\0${id}`;
+            if (id.startsWith("virtual:fuzor/page-script/"))
+                return `\0${id}`;
+            if (id.startsWith("virtual:fuzor/native-handler/"))
+                return `\0${id}`;
+            if (importer?.startsWith("\0virtual:fuzor/native-handler/") && id.startsWith(".")) {
+                const handler = [...nativeHandlers.values()].find(handler => importer === `\0virtual:fuzor/native-handler/${handler.id}.js`);
+                if (handler)
+                    return this.resolve(path.resolve(path.dirname(handler.source), id), undefined, { skipSelf: true });
+            }
+            if (importer?.startsWith("\0virtual:fuzor/page-script/")) {
+                const script = pageScripts.find(script => `\0${pageScriptId(script)}` === importer);
+                if (script)
+                    return this.resolve(id, script.source, { ...resolveOptions, skipSelf: true });
+            }
+            if (id.endsWith(".fragment.html")) {
+                const file = await this.resolve(id, importer, { ...resolveOptions, skipSelf: true });
+                if (file)
+                    return file.id.startsWith("\0fuzor:fragment:") ? file.id : `\0fuzor:fragment:${file.id}.js`;
+            }
+            if (id.startsWith("virtual:fuzor/closure/"))
+                return `\0fuzor:closure:${id.slice("virtual:fuzor/closure/".length)}.ts`;
+            if (id === "virtual:fuzor/views" || id === virtualId || Object.hasOwn(rendererModules, id))
+                return `\0${id}`;
+            if (id === "fuzor/ui" || id.startsWith("fuzor/ui/")) {
+                const projectImporter = importer && !importer.startsWith("\0") ? importer : path.join(vite.root, "package.json");
+                const resolved = await this.resolve(id, projectImporter, { ...resolveOptions, skipSelf: true });
+                if (resolved)
+                    return resolved;
+                // Virtual docs imports can resolve against Fuzor itself when the host
+                // does not expose a workspace link at the project root.
+                const fallback = id === "fuzor/ui" ? `fuzor/ui/${resolveOptions.ssr ? "server" : "client"}` : id;
+                const local = await this.resolve(fallback, fileURLToPath(import.meta.url), { ...resolveOptions, skipSelf: true });
+                if (local)
+                    return local;
+                try {
+                    return fileURLToPath(import.meta.resolve(fallback));
+                }
+                catch { }
+            }
+            if (!runtimes?.enabled)
+                return undefined;
+            // `virtual:fuzor/compiler/react@react18`: a build-time renderer for one runtime.
+            const renderer = /^(virtual:fuzor\/compiler\/(?:react|solid))@([a-z0-9]+)$/.exec(id);
+            if (renderer && Object.hasOwn(rendererModules, renderer[1]) && runtimes.keys().includes(renderer[2])) {
+                const resolved = `\0${id}`;
+                runtimeModules.set(resolved, () => runtimes.renderer(renderer[2], rendererModules[renderer[1]]));
+                return resolved;
+            }
+            const adapter = runtimes.adapter(id);
+            if (adapter) {
+                runtimeModules.set(adapter.id, adapter.load);
+                return adapter.id;
+            }
+            const scope = runtimes.scopeOf(importer);
+            if (!scope || !importer)
+                return undefined;
+            const insidePackage = runtimes.packageScope(importer.split("?")[0]);
+            if (insidePackage) {
+                // react-dom-18 importing react must get react-18, which is installed at the project root.
+                const mapped = runtimes.mapSpecifier(insidePackage, id);
+                return mapped ? this.resolve(mapped, path.join(vite?.root ?? process.cwd(), "package.json"), { ...resolveOptions, skipSelf: true }) : undefined;
+            }
+            if (!id.startsWith(".") && !id.startsWith("/"))
+                return undefined;
+            const resolved = await this.resolve(id, importer, { ...resolveOptions, skipSelf: true });
+            if (resolved && !resolved.external)
+                runtimes.assign(resolved.id.split("?")[0], scope);
+            return resolved;
         },
-        load(id) {
+        transform: {
+            order: "pre",
+            handler(code, id) {
+                if (!/\.[cm]?[jt]sx?$/.test(id.split("?")[0]) || id.includes("/node_modules/"))
+                    return undefined;
+                const workflow = compileWorkflows(code, id);
+                if (workflow)
+                    return workflow;
+                if (!runtimes?.enabled || id.startsWith(runtimes.resolvedPrefix))
+                    return undefined;
+                if (!/\.[cm]?[jt]sx?$/.test(id.split("?")[0]))
+                    return undefined;
+                const scope = runtimes.scopeOf(id);
+                if (!scope || runtimes.packageScope(id.split("?")[0]))
+                    return undefined;
+                return runtimes.transform(scope, code, id);
+            }
+        },
+        async load(id, loadOptions) {
+            if (id.startsWith("\0virtual:fuzor/route-client/")) {
+                await loadProject();
+                const route = scriptRoutes.find(route => `\0${routeScriptId(route)}` === id);
+                if (!route)
+                    throw new Error("Unknown Fuzor route client entry");
+                return `export const bindings = [${route.bindings.map(binding => `{ ...${JSON.stringify(binding)}, load: () => import(${JSON.stringify(pageScriptId(pageScripts.find(script => script.id === binding.id)))}) }`).join(",")}];`;
+            }
+            if (id.startsWith("\0virtual:fuzor/page-script/")) {
+                await loadProject();
+                const script = pageScripts.find(script => `\0${pageScriptId(script)}` === id);
+                if (!script)
+                    throw new Error("Unknown Fuzor page script");
+                this.addWatchFile(script.source);
+                const source = script.code ?? await readFile(script.source, "utf8");
+                const native = compileNativeScript(source, script);
+                if (native) {
+                    for (const handler of native.handlers)
+                        nativeHandlers.set(handler.id, handler);
+                    return (await import("vite")).transformWithEsbuild(native.code, script.source, { loader: script.language, target: "es2022", sourcefile: script.source });
+                }
+                const compiled = compilePageScript(source, script);
+                return (await import("vite")).transformWithEsbuild(compiled.code, script.source, { loader: script.language, target: "es2022", sourcemap: true, sourcefile: script.source }, compiled.map);
+            }
+            if (id.startsWith("\0virtual:fuzor/native-handler/")) {
+                const handler = [...nativeHandlers.values()].find(handler => id === `\0virtual:fuzor/native-handler/${handler.id}.js`);
+                if (!handler)
+                    throw new Error("Unknown native handler");
+                return (await import("vite")).transformWithEsbuild(handler.code, handler.source, { loader: handler.language, target: "es2022" });
+            }
+            if (id.startsWith("\0fuzor:closure:")) {
+                const refs = await references();
+                const closure = refs.closures.find(ref => id === `\0fuzor:closure:${ref.id}.ts`);
+                if (!closure)
+                    throw new Error("Unknown resumable closure reference");
+                return (await import("vite")).transformWithEsbuild(closure.code, id, { loader: "ts", target: "es2022" }).then(result => result.code);
+            }
+            if (options.serverComponents?.references) {
+                const refs = await references();
+                if (id === "\0virtual:fuzor/views") {
+                    if (loadOptions?.ssr)
+                        return `export const manifest=${JSON.stringify({ buildId: viewBuildId, templates: refs.templates })}; export const components=${JSON.stringify(refs.clients.map(ref => ref.id))}; export const handlers=${JSON.stringify([...refs.handlers.map(ref => ref.id), ...refs.closures.map(ref => ref.id)])};`;
+                    return browserReferencesCode(refs, viewBuildId, file => "/" + file);
+                }
+                if (loadOptions?.ssr) {
+                    const stub = referenceStub(id.split("?")[0], refs);
+                    if (stub)
+                        return stub;
+                }
+            }
+            if (id.startsWith("\0fuzor:fragment:")) {
+                const file = id.slice("\0fuzor:fragment:".length, -3);
+                this.addWatchFile(file);
+                return readFile(file, "utf8").then(html => `export default ${JSON.stringify(compileFragment(html))};`);
+            }
+            if (Object.hasOwn(rendererModules, id.slice(1)))
+                return rendererModules[id.slice(1)];
+            const runtimeModule = runtimeModules.get(id);
+            if (runtimeModule)
+                return runtimeModule();
+            if (!loadOptions?.ssr && !nested && vite) {
+                const file = id.split("?")[0];
+                const relative = path.relative(vite.root, file).split(path.sep).join("/");
+                if (options.serverComponents && path.resolve(vite.root, options.serverComponents.server) === file || serverModuleFiles.includes(relative) || relative.startsWith("api/") || /\.server\.[cm]?[jt]sx?$/.test(relative)) {
+                    throw new Error(`${relative} is server-only and cannot be imported by browser code. Read its data with <fuzor-data> or routeData() instead.`);
+                }
+            }
             if (id !== resolvedVirtualId)
                 return undefined;
+            await loadProject();
+            const mixedClient = profile.mixed && project?.routes.some(route => route.policy?.navigation === "spa");
+            const scriptRegistry = scriptRoutes.map(route => `${JSON.stringify(route.path)}: () => import(${JSON.stringify(routeScriptId(route))}).catch(reloadOnStaleDeployment)`).join(",\n");
             const registry = islands.map((island) => {
                 const load = island.file.endsWith(".vue")
-                    ? `Promise.all([import(${JSON.stringify(island.file)}), import("fuzor/islands/vue")]).then(([component, adapter]) => adapter.vueIsland(component.default))`
-                    : `import(${JSON.stringify(island.file)})`;
+                    ? `Promise.all([import(${JSON.stringify(island.file)}), import("fuzor/islands/vue")]).then(([component, adapter]) => adapter.vueIsland(component.default)).catch(reloadOnStaleDeployment)`
+                    : `import(${JSON.stringify(island.file)}).catch(reloadOnStaleDeployment)`;
                 return `${JSON.stringify(island.name)}: () => ${load}`;
             }).join(",\n");
-            return `import { ${target === "spa" ? "createRouter" : "mountIslands"} } from "${target === "spa" ? "fuzor/runtime" : "fuzor/runtime/islands"}";
+            const withData = target === "mpa" && !!project?.routes.some(route => route.serverData);
+            const hasDocs = (project?.routes ?? []).some(route => route.path === "/docs/" || route.path.startsWith("/docs/"));
+            const routerModule = profile.electron || options.navigation === "embedded" ? "fuzor/runtime/router/embedded" : options.navigation === "navigation-api" ? "fuzor/runtime/router/navigation-api" : "fuzor/runtime";
+            const imports = [
+                (target === "spa" || mixedClient)
+                    ? `import { createRouter } from "${routerModule}"; import { reloadOnStaleDeployment } from "fuzor/runtime/islands";`
+                    : 'import { mountIslands, islandErrorHandler, reloadOnStaleDeployment } from "fuzor/runtime/islands";',
+                ...(target === "mpa" ? ['import { mountPageScripts } from "fuzor/runtime/page-scripts"; import { stripBase } from "fuzor/runtime";'] : []),
+                ...(options.serverComponents ? [options.serverComponents.references ? 'import generatedViewOptions from "virtual:fuzor/views";' : "", options.serverComponents.client ? `import suppliedViewOptions from ${JSON.stringify("/" + options.serverComponents.client)};` : "", `const viewOptions = { ${options.serverComponents.references ? "...generatedViewOptions" : ""}${options.serverComponents.references && options.serverComponents.client ? "," : ""}${options.serverComponents.client ? "...suppliedViewOptions" : ""} };`, (target === "spa" || mixedClient) ? 'import { makeClientRouteMatcher } from "fuzor/runtime"; import { serverViewRoutes } from "fuzor/server-components/navigation"; import { createViewRenderer } from "fuzor/server-components/browser";' : 'import { createViewRenderer } from "fuzor/server-components/browser";'] : []),
+                ...(mixedClient ? ['import { mountIslands, islandErrorHandler } from "fuzor/runtime/islands";'] : []),
+                ...(withData ? ['import { loadRouteData } from "fuzor/runtime/data";'] : []),
+                ...(hasDocs ? ['import { mountDocsUi } from "fuzor/runtime/docs-ui";'] : [])
+            ];
+            const docsInit = hasDocs ? `let stopDocsUi;
+let docsDisposed = false;
+const hideDocs = event => { if (!event.persisted) disposeDocs(); };
+const disposeDocs = () => {
+  if (docsDisposed) return;
+  docsDisposed = true;
+  window.removeEventListener("pagehide", hideDocs);
+  stopDocsUi?.();
+};
+void mountDocsUi({ document, base: import.meta.env.BASE_URL }).then(stop => {
+  stopDocsUi = stop;
+  if (docsDisposed) stop();
+}, error => console.error(error));
+window.addEventListener("pagehide", hideDocs);
+if (import.meta.hot) import.meta.hot.dispose(disposeDocs);
+` : "";
+            const effectiveViewOptions = `...viewOptions, manifest: { ...viewOptions.manifest, buildId: ${JSON.stringify(viewBuildId)} }`;
+            const spaStart = `export const router = (${mixedClient ? 'outlet.getAttribute("data-fuzor-navigation") === "spa" && ' : ""}!outlet.hasAttribute("data-fuzor-not-found") && !outlet.hasAttribute("data-fuzor-error")) ? createRouter(outlet, { islands, scripts, base: import.meta.env.BASE_URL${options.serverComponents ? `, renderer: serverViewRoutes({ ${effectiveViewOptions}, routes: ${JSON.stringify(options.serverComponents.routes)}, acceptsRoute: path => !${mixedClient} || [...document.querySelectorAll("template[data-fuzor-route]")].some(t => t.getAttribute("data-fuzor-route") === path || t.hasAttribute("data-fuzor-request-pattern") && makeClientRouteMatcher({[t.getAttribute("data-fuzor-request-pattern")]: "/"})(path)), base: import.meta.env.BASE_URL })` : ""}${options.clientRoutes ? `, clientRoutes: ${JSON.stringify(options.clientRoutes)}` : ""}${options.routeTree ? `, routeTree: ${JSON.stringify(options.routeTree)}` : ""}${options.viewTransitions ? ", viewTransitions: true" : ""}${options.prefetch === "intent" ? ', prefetch: "intent"' : ""} }) : undefined;
+export const ready = router ? router.start() : Promise.resolve(undefined);
+void ready.catch(error => console.error(error));
+if (import.meta.hot) import.meta.hot.dispose(() => { void router?.dispose(); });`;
+            const mpaStart = `${withData ? `if (outlet.hasAttribute("data-fuzor-data") && !outlet.hasAttribute("data-fuzor-data-ready")) void loadRouteData(outlet).catch(error => { if (error?.name !== "AbortError") console.error(error); });
+` : ""}if (!/^https?:$/.test(location.protocol)) console.error("Fuzor MPA builds need an HTTP(S) server: their root-relative links and assets do not resolve over " + location.protocol + " URLs. Use an inline SPA build (fuzor build --target spa --inline) for embedded apps.");
+const lifetime = new AbortController();
+let cleanup;
+const dispose = () => { lifetime.abort(); void cleanup?.(); };
+${options.serverComponents ? `const viewRenderer = document.querySelector("script[data-fuzor-snapshot]") ? createViewRenderer(outlet, { ${effectiveViewOptions} }) : undefined;
+const mountComponents = viewRenderer ? viewRenderer.resume().then(() => () => viewRenderer.dispose()) : mountIslands(outlet, islands, islandErrorHandler, { signal: lifetime.signal });` : `const mountComponents = mountIslands(outlet, islands, islandErrorHandler, { signal: lifetime.signal });`}
+${options.serverComponents ? "const viewRendererActive = !!viewRenderer;" : "const viewRendererActive = false;"}
+const pathname = stripBase(location.pathname, import.meta.env.BASE_URL) ?? location.pathname;
+const routePath = pathname.endsWith("/") ? pathname : pathname + "/";
+const scriptRoute = Object.hasOwn(scripts, routePath) ? routePath : outlet.getAttribute("data-fuzor-pattern") ?? "";
+const mount = (async () => { const stopComponents = await mountComponents; try { const stopScripts = await mountPageScripts(outlet, viewRendererActive ? {} : scripts, { signal: lifetime.signal, route: scriptRoute }); return async () => { await stopScripts(); await stopComponents(); }; } catch (error) { await stopComponents(); throw error; } })();
+void mount.then(stop => {
+  cleanup = stop;
+  if (lifetime.signal.aborted) void stop();
+}, error => { if (!lifetime.signal.aborted) console.error(error); });
+window.addEventListener("pagehide", event => { if (!event.persisted) dispose(); });
+if (import.meta.hot) import.meta.hot.dispose(dispose);`;
+            return `${imports.join("\n")}
 const islands = { ${registry} };
+const scripts = { ${scriptRegistry} };
 const outlet = document.querySelector("fuzor-router");
 if (!outlet) throw new Error("Fuzor outlet is missing");
-${target === "spa"
-                ? "if (!outlet.hasAttribute(\"data-fuzor-not-found\")) void createRouter(outlet, { islands }).start();"
-                : "void mountIslands(outlet, islands);"}`;
+window.addEventListener("vite:preloadError", event => { event.preventDefault(); void reloadOnStaleDeployment(event.payload).catch(error => console.error(error)); });
+${docsInit}${mixedClient ? spaStart + "\nif (!router) {\n" + mpaStart + "\n}" : target === "spa" ? spaStart : mpaStart}`;
         },
         transformIndexHtml: {
             order: "pre",
             async handler(raw, context) {
+                if (nested)
+                    return raw;
                 const compiled = await loadProject();
-                const pathname = target === "spa" ? "/" : new URL(context.path, "http://fuzor.local").pathname;
-                const currentPath = compiled.routes.some((route) => route.path === (pathname === "/" ? "/" : `${pathname.replace(/\/+$/, "")}/`)) ? pathname : "/";
-                let html = replaceOutlet(raw, outletFor(compiled, target, currentPath));
-                if (needsSolidHydration) {
-                    const { generateHydrationScript } = await import("solid-js/web");
-                    html = html.replace("</head>", `${generateHydrationScript()}</head>`);
+                const requested = new URL(context.path, "http://fuzor.local").pathname;
+                const pathname = stripBase(requested, pathBase) ?? requested;
+                const currentPath = findRoute(compiled, pathname) ? pathname : "/";
+                parseRoutePolicy(raw, path.join(vite.root, "index.html"), false);
+                const shell = compilePlatformBlocks(raw, profile.platform, path.join(vite.root, "index.html"));
+                shellHead = readDocumentHead(shell);
+                let html = applyDocumentMetadata(replaceOutlet(shell, outletFor(compiled, target, currentPath, fallbacks(), profile.mixed)), pageHead(shellHead, findRoute(compiled, currentPath)?.metadata ?? {}));
+                if (inline && target === "spa") {
+                    const initial = findRoute(compiled, currentPath);
+                    const script = await inlineInitialRouteScript({ base: pathBase, alwaysHash: profile.electron || options.navigation === "embedded", ...(options.clientRoutes ? { clientRoutes: options.clientRoutes } : {}) });
+                    // A route never becomes visible until the synchronous selector chooses it.
+                    html = html.replace(/<fuzor-router\b[^>]*>[\s\S]*?<\/fuzor-router>/, "<fuzor-router></fuzor-router>");
+                    const fallback = `<noscript>${initial?.html ?? ""}<p>JavaScript is required to navigate this single-file app.</p></noscript>`;
+                    html = html.replace(outletEnd, () => `${script}${fallback}${outletEnd}`);
                 }
+                if (options.generator !== false)
+                    html = applyGeneratorMetadata(html);
+                if (hydrationScript)
+                    html = html.replace("</head>", `${hydrationScript}</head>`);
+                if (vite.command === "serve")
+                    html = withStaticModuleImports(html);
                 html = html.replace("</head>", `<script type="module">import "${virtualId}";</script></head>`);
                 return html;
             }
         },
         configureServer(server) {
+            if (nested)
+                return;
             devServer = server;
-            if (withServer || target === "mpa") {
-                server.middlewares.use(async (request, response, next) => {
-                    const pathname = new URL(request.url ?? "/", "http://fuzor.local").pathname;
-                    if (withServer && !pathname.startsWith("/@") && !pathname.startsWith("/__") && !pathname.includes(".")) {
-                        try {
+            releaseRuntimeHooks();
+            releaseRuntimeHooks = runtimes?.registerNodeHooks() ?? (() => { });
+            // Install before profile detection changes so adding the first server module works in SPA too.
+            server.middlewares.use(async (request, response, next) => {
+                const requested = new URL(request.url ?? "/", "http://fuzor.local").pathname;
+                const pathname = stripBase(requested, pathBase);
+                if (pathname === undefined)
+                    return next();
+                if (pathname === "/search-index.json" && options.searchIndex) {
+                    try {
+                        response.setHeader("content-type", "application/json; charset=utf-8");
+                        response.end(searchIndex(await loadProject(), options.searchIndex));
+                    }
+                    catch (error) {
+                        next(error);
+                    }
+                    return;
+                }
+                if (!withServer && target === "spa")
+                    return next();
+                const dataRequest = pathname.startsWith(`${serverDataPrefix}/`);
+                const apiRequest = apiFiles.length > 0 && (pathname === "/api" || pathname.startsWith("/api/"));
+                // Explicit Vite proxies own their upstream APIs; server views must not turn them into HTML routes.
+                if (!apiRequest && Object.keys(server.config.server.proxy ?? {}).some(prefix => prefix.startsWith("^") ? new RegExp(prefix).test(requested) : requested === prefix || requested.startsWith(prefix + "/")))
+                    return next();
+                if (withServer && (dataRequest || apiRequest || !pathname.startsWith("/@") && !pathname.startsWith("/__") && !pathname.includes("."))) {
+                    const controller = new AbortController();
+                    const abort = () => { if (!response.writableFinished)
+                        controller.abort(); };
+                    request.once("aborted", abort);
+                    response.once("close", abort);
+                    try {
+                        const onError = (error) => server.config.logger.error(`[fuzor] ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+                        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "fuzor.local"}`);
+                        let result;
+                        if (apiRequest) {
+                            // Rescanned per request so new endpoint files work without restarting.
+                            const api = await loadApiModules(findApiRoutes(vite.root), file => createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule(file));
+                            result = await createServerHandler({ documents: {}, notFoundDocument: "", ...(pathBase === "/" ? {} : { base: pathBase }) }, { api, onError })(toWebRequest(request, { url, signal: controller.signal }));
+                        }
+                        else {
                             const raw = await readFile(path.join(vite.root, "index.html"), "utf8");
                             const template = await server.transformIndexHtml("/", raw);
                             const compiled = await loadProject();
-                            const notFoundDocument = replaceOutlet(template, '<fuzor-router data-fuzor-not-found><h1>Not found</h1></fuzor-router>');
-                            const manifest = target === "spa"
-                                ? { document: template, routes: Object.fromEntries(compiled.routes.map((route) => [route.path, true])), notFoundDocument }
-                                : { documents: Object.fromEntries(compiled.routes.map((route) => [route.path, replaceOutlet(template, `<fuzor-router>${route.html}</fuzor-router>`)])), notFoundDocument };
-                            const result = await createServerHandler(manifest)(new Request(new URL(request.url ?? "/", "http://fuzor.local"), { method: request.method ?? "GET" }));
-                            response.writeHead(result.status, Object.fromEntries(result.headers));
-                            response.end(Buffer.from(await result.arrayBuffer()));
-                        }
-                        catch (error) {
-                            next(error);
+                            const manifest = serverManifest(compiled, target, template, pathBase, fallbacks(), withStaticModuleImports, options.clientRoutes, `/${vite.build.assetsDir}/`, profile.mixed);
+                            const data = dataRequest || compiled.routes.some(route => route.policy?.rendering === "request") ? await loadRouteDataModules(compiled, file => createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule(file), vite.root) : undefined;
+                            const views = options.serverComponents ? await generatedViews((await createEnvironmentModuleRuntime(server, moduleEnvironment, environmentApiEnabled).loadModule("/" + options.serverComponents.server)).default) : undefined;
+                            if (views && JSON.stringify(Object.keys(views.routes).sort()) !== JSON.stringify([...options.serverComponents.routes].sort()))
+                                throw new Error("Server view routes must match serverComponents.routes.");
+                            result = await createServerHandler(manifest, { ...(data ? { data } : {}), ...(views ? { views: { ...views, manifest: { ...views.manifest, buildId: viewBuildId }, documentPatterns: manifest.requestPatterns ?? {}, document: serverViewDocument(template), documents: Object.fromEntries(Object.entries("documents" in manifest ? manifest.documents : manifest.routeDocuments ?? {}).map(([route, html]) => [route, serverViewDocument(html)])) } } : {}), onError })(toWebRequest(request, { url, signal: controller.signal }));
                         }
-                        return;
-                    }
-                    if (request.method !== "GET")
-                        return next();
-                    const normalized = pathname === "/" ? "/" : `${pathname.replace(/\/+$/, "")}/`;
-                    if (normalized === "/" || !(await loadProject()).routes.some((route) => route.path === normalized))
-                        return next();
-                    try {
-                        const raw = await readFile(path.join(vite.root, "index.html"), "utf8");
-                        const html = await server.transformIndexHtml(pathname, raw);
-                        response.setHeader("content-type", "text/html; charset=utf-8");
-                        response.end(html);
+                        await writeWebResponse(response, result, { method: request.method ?? "GET", signal: controller.signal });
                     }
                     catch (error) {
-                        next(error);
+                        if (!controller.signal.aborted) {
+                            if (response.headersSent) {
+                                server.config.logger.error(String(error));
+                                response.destroy();
+                            }
+                            else
+                                next(error);
+                        }
                     }
-                });
-            }
+                    finally {
+                        request.removeListener("aborted", abort);
+                        response.removeListener("close", abort);
+                    }
+                    return;
+                }
+                if (request.method !== "GET")
+                    return next();
+                const normalized = routeKey(pathname);
+                const redirect = normalized === undefined ? undefined : (await loadProject()).redirects?.[normalized];
+                if (redirect !== undefined) {
+                    response.writeHead(308, { location: /^https?:\/\//i.test(redirect) ? redirect : withBase(redirect, pathBase) }).end();
+                    return;
+                }
+                if (normalized === "/" || !findRoute(await loadProject(), pathname))
+                    return next();
+                try {
+                    const raw = await readFile(path.join(vite.root, "index.html"), "utf8");
+                    const html = await server.transformIndexHtml(requested, raw);
+                    response.setHeader("content-type", "text/html; charset=utf-8");
+                    response.end(html);
+                }
+                catch (error) {
+                    next(error);
+                }
+            });
             server.watcher.on("add", (file) => {
-                if (["/pages/", "/components/", "/layouts/", "/islands/"].some((part) => file.includes(part))) {
+                if (pageScripts.some(script => script.source === file) || options.serverComponents && (file.endsWith(".fragment.html") || options.serverComponents.references && file.startsWith(path.resolve(vite.root, options.serverComponents.references) + path.sep) || file === path.resolve(vite.root, options.serverComponents.server) || options.serverComponents.client && file === path.resolve(vite.root, options.serverComponents.client)) || ["/pages/", "/components/", "/layouts/", "/islands/", "/api/"].some((part) => file.replaceAll("\\", "/").includes(part))) {
                     void refresh(server).catch((error) => server.config.logger.error(String(error)));
                 }
             });
             server.watcher.on("unlink", (file) => {
-                if (["/pages/", "/components/", "/layouts/", "/islands/"].some((part) => file.includes(part))) {
+                if (pageScripts.some(script => script.source === file) || ["/pages/", "/components/", "/layouts/", "/islands/", "/api/"].some((part) => file.replaceAll("\\", "/").includes(part))) {
                     void refresh(server).catch((error) => server.config.logger.error(String(error)));
                 }
             });
         },
+        buildStart() {
+            buildFailed = false;
+            bundleWritten = false;
+            if (!nested && vite.command === "build") {
+                releaseRuntimeHooks();
+                releaseRuntimeHooks = runtimes?.registerNodeHooks() ?? (() => { });
+            }
+        },
+        async generateBundle(_output, bundle) {
+            if (nested || vite.build.ssr)
+                return;
+            if (runtimes?.enabled) {
+                // A module assigned to a runtime but also imported by other code would run with two framework versions.
+                for (const [file, runtime] of runtimes.assigned()) {
+                    const importers = this.getModuleInfo(file)?.importers ?? [];
+                    const foreign = importers.find(importer => runtimes.scopeOf(importer)?.key !== runtime);
+                    if (foreign)
+                        this.error(`${path.relative(vite.root, file)} is imported by ${runtime} islands and by ${path.relative(vite.root, foreign)}. Keep modules that use a framework runtime separate from other code.`);
+                }
+            }
+            // Which files each island downloads, for `fuzor routes` (written outside the output directory).
+            const chunks = Object.values(bundle).filter((item) => item.type === "chunk");
+            inlineModuleFiles = chunks.map(chunk => chunk.fileName);
+            const byName = new Map(chunks.map(chunk => [chunk.fileName, chunk]));
+            const collect = (fileName, seen) => {
+                if (seen.has(fileName))
+                    return;
+                seen.add(fileName);
+                for (const imported of byName.get(fileName)?.imports ?? [])
+                    collect(imported, seen);
+            };
+            const report = {};
+            islandStyles = {};
+            for (const island of islands) {
+                const chunk = chunks.find(item => item.facadeModuleId === path.join(vite.root, island.file));
+                if (!chunk)
+                    continue;
+                const files = new Set();
+                collect(chunk.fileName, files);
+                const css = [...files].flatMap(file => [...(byName.get(file)?.viteMetadata?.importedCss ?? [])]);
+                report[island.name] = { files: [...files], css: [...new Set(css)] };
+                islandStyles[island.name] = report[island.name].css;
+            }
+            const file = path.join(vite.root, ".fuzor", `chunks-${target}${withServer ? "-server" : ""}.json`);
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, JSON.stringify({ inline, islands: Object.fromEntries(islands.map(module => [module.name, report[module.name]])) }, null, 2), "utf8");
+        },
+        buildEnd(error) { if (error)
+            buildFailed = true; },
+        // Errors while generating or writing chunks happen after buildEnd; only a written bundle is post-processed.
+        renderError() { buildFailed = true; },
+        writeBundle() { bundleWritten = true; },
         async closeBundle() {
-            if (vite.command !== "build")
+            // Rollup still calls closeBundle after a failed build; post-processing would hide the real error.
+            if (nested)
                 return;
-            const outDir = path.resolve(vite.root, vite.build.outDir);
-            if (target === "spa" && inline) {
-                let html = await readFile(path.join(outDir, "index.html"), "utf8");
-                const assetFiles = new Set();
-                for (const match of html.matchAll(/<script\b[^>]*\bsrc="([^"]+)"[^>]*><\/script>/g)) {
-                    const url = match[1];
-                    if (!url.endsWith(".js"))
-                        continue;
-                    const file = path.join(outDir, url.replace(/^\//, ""));
-                    const source = await readFile(file, "utf8");
-                    html = html.replace(match[0], () => `<script type="module">${source.replace(/<\/script/gi, "<\\/script")}</script>`);
-                    assetFiles.add(file);
+            try {
+                if (vite.command !== "build")
+                    return;
+                if (buildFailed || !bundleWritten)
+                    return;
+                const outDir = path.resolve(vite.root, vite.build.outDir);
+                const compiled = await loadProject();
+                const artifact = { version: 1, buildId: viewBuildId, platform: profile.platform, mode: profile.mixed ? "mixed" : target, inline, backendRequired: compiled.routes.some(route => route.policy?.rendering === "request"), routes: compiled.routes.map(route => ({ path: route.path, ...route.policy, backendData: !!route.serverData, ...(route.requestPattern ? { requestPattern: route.requestPattern } : {}) })) };
+                await mkdir(path.join(vite.root, ".fuzor"), { recursive: true });
+                if (!inline)
+                    await writeFile(path.join(outDir, "fuzor.manifest.json"), JSON.stringify(artifact, null, 2) + "\n");
+                if (target === "spa" && inline) {
+                    const inlined = await inlineDocumentAssets(await readFile(path.join(outDir, "index.html"), "utf8"), outDir, inlineModuleFiles);
+                    const html = inlined.html;
+                    const assetFiles = inlined.files;
+                    await writeFile(path.join(outDir, "index.html"), html, "utf8");
+                    for (const file of assetFiles)
+                        await unlink(file);
+                    const assetDir = path.join(outDir, "assets");
+                    try {
+                        const remaining = await readdir(assetDir);
+                        if (remaining.length > 0)
+                            throw new Error(`SPA inline build left external assets: ${remaining.join(", ")}`);
+                        await rmdir(assetDir);
+                    }
+                    catch (error) {
+                        if (error.code !== "ENOENT")
+                            throw error;
+                    }
+                    const remainingFiles = await readdir(outDir);
+                    if (remainingFiles.length !== 1 || remainingFiles[0] !== "index.html") {
+                        throw new Error(`An inline SPA build must be a single index.html, but these files are outside it: ${remainingFiles.filter((file) => file !== "index.html").join(", ")}. ` +
+                            "They usually come from public/, which Vite copies unchanged. Import images and fonts from source files instead (inline builds embed them as data URLs), remove the public files, or use the regular SPA build.");
+                    }
+                    if (profile.electron)
+                        await writeElectronScaffold(outDir);
+                    return;
                 }
-                for (const match of html.matchAll(/<link\b[^>]*\brel="stylesheet"[^>]*\bhref="([^"]+)"[^>]*>/g)) {
-                    const file = path.join(outDir, match[1].replace(/^\//, ""));
-                    const source = await readFile(file, "utf8");
-                    html = html.replace(match[0], () => `<style>${source.replace(/<\/style/gi, "<\\/style")}</style>`);
-                    assetFiles.add(file);
+                const styled = (html) => withIslandStyles(html, islandStyles, vite.base);
+                const rootHtml = styled(await readFile(path.join(outDir, "index.html"), "utf8"));
+                await writeFile(path.join(outDir, "index.html"), rootHtml, "utf8");
+                if (withServer) {
+                    const serverDir = process.env.FUZOR_STAGE_DIR ? path.resolve(process.env.FUZOR_STAGE_DIR, profile.backendOutDir) : path.resolve(vite.root, profile.backendOutDir);
+                    const manifest = { ...serverManifest(compiled, target, rootHtml, pathBase, fallbacks(), styled, options.clientRoutes, `/${vite.build.assetsDir}/`, profile.mixed), buildId: viewBuildId };
+                    await mkdir(serverDir, { recursive: true });
+                    await writeFile(path.join(serverDir, "fuzor.manifest.json"), JSON.stringify({ ...artifact, clientDirectory: path.relative(serverDir, outDir).split(path.sep).join("/") }, null, 2) + "\n");
+                    const dataRoutes = compiled.routes.filter(route => route.serverData);
+                    const refs = options.serverComponents?.references ? await references() : undefined;
+                    if (!dataRoutes.length && !apiFiles.length && !options.serverComponents && !options.serverExternal) {
+                        await writeFile(path.join(serverDir, "entry.mjs"), `import { createServerHandler } from "fuzor/server";\n` +
+                            `export const manifest = ${JSON.stringify(manifest)};\n` +
+                            `export const handler = createServerHandler(manifest);\n`, "utf8");
+                    }
+                    else {
+                        // Server modules are bundled for Node; documents remain precompiled strings in the manifest.
+                        const files = [...new Set(dataRoutes.map(route => route.serverData))];
+                        const entryId = "virtual:fuzor/server-entry";
+                        const code = [
+                            `import { createServerHandler, isServerData } from "fuzor/server";`,
+                            ...(options.serverComponents ? [`import suppliedViews from ${JSON.stringify(path.resolve(vite.root, options.serverComponents.server))};`, `const views = { ...suppliedViews${refs ? `, manifest: ${JSON.stringify({ buildId: viewBuildId, templates: refs.templates })}, components: ${JSON.stringify(refs.clients.map(ref => ref.id))}, handlers: ${JSON.stringify([...refs.handlers.map(ref => ref.id), ...refs.closures.map(ref => ref.id)])}` : ""} };`, `if (JSON.stringify(Object.keys(views.routes).sort()) !== ${JSON.stringify(JSON.stringify([...options.serverComponents.routes].sort()))}) throw new Error("Server view routes must match serverComponents.routes.");`] : []),
+                            ...files.map((file, index) => `import data${index} from ${JSON.stringify(file)};`),
+                            ...apiFiles.map((route, index) => `import * as api${index} from ${JSON.stringify(route.file)};`),
+                            `const modules = [${files.map((_, index) => `data${index}`).join(", ")}];`,
+                            `const sources = ${JSON.stringify(files.map(file => path.relative(vite.root, file).split(path.sep).join("/")))};`,
+                            `modules.forEach((module, index) => { if (!isServerData(module)) throw new Error(sources[index] + " must export default defineServerData(...) from \\"fuzor/server\\"."); });`,
+                            `export const manifest = ${JSON.stringify(manifest)};`,
+                            `const routes = ${JSON.stringify(dataRoutes.map(route => [route.path, files.indexOf(route.serverData), route.params ?? null]))};`,
+                            `const api = [${apiFiles.map((route, index) => `{ pattern: ${JSON.stringify(route.pattern)}, segments: ${JSON.stringify(route.segments)}, source: ${JSON.stringify(route.relative)}, module: api${index} }`).join(", ")}];`,
+                            `export const handler = createServerHandler(manifest, { data: Object.fromEntries(routes.map(([route, index, params]) => [route, params ? { data: modules[index], params } : { data: modules[index] }])), api${options.serverComponents ? `, views: { ...views, manifest: { ...views.manifest, buildId: ${JSON.stringify(viewBuildId)} }, documentPatterns:${JSON.stringify(manifest.requestPatterns ?? {})}, document: ${JSON.stringify(serverViewDocument(rootHtml))}, documents:${JSON.stringify(Object.fromEntries(Object.entries("documents" in manifest ? manifest.documents : manifest.routeDocuments ?? {}).map(([route, html]) => [route, serverViewDocument(html)])))} }` : ""} });`
+                        ].join("\n");
+                        await nestedServer.run(true, () => viteBuild({
+                            root: vite.root, mode: vite.mode, configFile: vite.configFile ?? false, logLevel: "error", publicDir: false,
+                            // One runtime copy: the entry and server modules share fuzor/server and effect, either both imported from
+                            // node_modules (the default) or, for what `serverExternal` does not name, bundled once into the output.
+                            ssr: options.serverExternal ? { external: [...options.serverExternal], noExternal: true } : { external: ["fuzor", "effect"] },
+                            plugins: [compiledFragmentsPlugin(), workflowPlugin(), ...(refs ? [{ name: "fuzor:server-references", load: (id) => referenceStub(id, refs) }] : []), { name: "fuzor:server-entry", resolveId: id => id === entryId ? `\0${entryId}` : undefined, load: id => id === `\0${entryId}` ? code : undefined }],
+                            build: { ssr: true, outDir: serverDir, emptyOutDir: false, copyPublicDir: false, minify: false,
+                                rollupOptions: { input: entryId, output: { entryFileNames: "entry.mjs", chunkFileNames: "chunks/[name]-[hash].mjs", format: "es" } } }
+                        }));
+                    }
+                    // The same finished documents are also written to client/ below, so it can be served by a CDN or
+                    // static host with only /api and server data requests reaching the server.
+                    if (profile.adapter === "cloudflare")
+                        await writeCloudflareOutput(serverDir, vite.root, target, pathBase, outDir, [...compiled.routes.filter(route => route.policy?.rendering === "request").map(route => route.requestPattern ? route.requestPattern.slice(0, route.requestPattern.indexOf(":")) + "*" : route.path), ...(options.serverComponents?.routes ?? []).map(pattern => pattern.includes(":") ? pattern.slice(0, pattern.indexOf(":")) + "*" : pattern)], path.relative(path.resolve(vite.root, profile.backendOutDir), process.env.FUZOR_STAGE_DIR && outDir.startsWith(path.resolve(process.env.FUZOR_STAGE_DIR) + path.sep) ? path.resolve(vite.root, path.relative(process.env.FUZOR_STAGE_DIR, outDir)) : outDir).split(path.sep).join("/"));
                 }
-                await writeFile(path.join(outDir, "index.html"), html, "utf8");
-                for (const file of assetFiles)
-                    await unlink(file);
-                const assetDir = path.join(outDir, "assets");
-                try {
-                    const remaining = await readdir(assetDir);
-                    if (remaining.length > 0)
-                        throw new Error(`SPA inline build left external assets: ${remaining.join(", ")}`);
-                    await rmdir(assetDir);
+                const index = searchIndex(compiled, options.searchIndex);
+                if (index)
+                    await writeFile(path.join(outDir, "search-index.json"), index, "utf8");
+                const redirects = Object.entries(compiled.redirects ?? {}).map(([from, to]) => [from, /^https?:\/\//i.test(to) ? to : withBase(to, pathBase)]);
+                if (redirects.length) {
+                    await writeFile(path.join(outDir, "_redirects"), redirects.map(([from, to]) => `${withBase(from, pathBase)} ${to} 308`).join("\n") + "\n", "utf8");
                 }
-                catch (error) {
-                    if (error.code !== "ENOENT")
-                        throw error;
+                // Static hosts read cache rules from _headers (Cloudflare, Netlify); servers send the same values.
+                const lifetimes = compiled.routes.filter(route => route.metadata?.revalidate);
+                if (target === "mpa" && lifetimes.length) {
+                    await writeFile(path.join(outDir, "_headers"), lifetimes.map(route => {
+                        const seconds = route.metadata.revalidate;
+                        return `${withBase(route.path, pathBase)}\n  Cache-Control: public, max-age=0, s-maxage=${seconds}, stale-while-revalidate=${seconds}\n`;
+                    }).join(""), "utf8");
                 }
-                const remainingFiles = await readdir(outDir);
-                if (remainingFiles.length !== 1 || remainingFiles[0] !== "index.html") {
-                    throw new Error(`SPA inline build left external files: ${remainingFiles.filter((file) => file !== "index.html").join(", ")}`);
+                if (target === "spa")
+                    return;
+                for (const [from, to] of redirects) {
+                    const outputFile = path.join(outDir, decodeURIComponent(from.slice(1)), "index.html");
+                    await mkdir(path.dirname(outputFile), { recursive: true });
+                    await writeFile(outputFile, redirectDocument(to), "utf8");
                 }
-                return;
-            }
-            const compiled = await loadProject();
-            const rootHtml = await readFile(path.join(outDir, "index.html"), "utf8");
-            if (withServer) {
-                const serverDir = path.resolve(outDir, "../server");
-                const notFoundDocument = replaceOutlet(rootHtml, '<fuzor-router data-fuzor-not-found><h1>Not found</h1></fuzor-router>');
-                const manifest = target === "spa"
-                    ? { document: rootHtml, routes: Object.fromEntries(compiled.routes.map((route) => [route.path, true])), notFoundDocument }
-                    : { documents: Object.fromEntries(compiled.routes.map((route) => [route.path, replaceOutlet(rootHtml, `<fuzor-router>${route.html}</fuzor-router>`)])), notFoundDocument };
-                await mkdir(serverDir, { recursive: true });
-                await writeFile(path.join(serverDir, "entry.mjs"), `import { createServerHandler } from "fuzor/server";\n` +
-                    `export const manifest = ${JSON.stringify(manifest)};\n` +
-                    `export const handler = createServerHandler(manifest);\n`, "utf8");
-                await unlink(path.join(outDir, "index.html"));
-                return;
+                // Static hosts such as Cloudflare Pages and Netlify serve the nearest 404.html for a missing URL.
+                const { notFoundDocument, notFoundDocuments } = serverManifest(compiled, "mpa", rootHtml, pathBase, fallbacks(), styled);
+                for (const [scope, document] of Object.entries(notFoundDocuments ?? { "/": notFoundDocument })) {
+                    const outputFile = path.join(outDir, decodeURIComponent(scope.slice(1)), "404.html");
+                    await mkdir(path.dirname(outputFile), { recursive: true });
+                    await writeFile(outputFile, document, "utf8");
+                }
+                for (const route of compiled.routes) {
+                    if (route.path === "/" || route.policy?.rendering === "request")
+                        continue;
+                    const outputFile = path.join(outDir, decodeURIComponent(route.path.slice(1)), "index.html");
+                    await mkdir(path.dirname(outputFile), { recursive: true });
+                    await writeFile(outputFile, styled(applyDocumentMetadata(replaceOutlet(rootHtml, outletFor(compiled, "mpa", route.path, fallbacks(), profile.mixed)), pageHead(shellHead, route.metadata ?? {}))), "utf8");
+                }
+                if (compiled.routes.find(route => route.path === "/")?.policy?.rendering === "request")
+                    await unlink(path.join(outDir, "index.html"));
             }
-            if (target === "spa")
-                return;
-            for (const route of compiled.routes) {
-                if (route.path === "/")
-                    continue;
-                const outputFile = path.join(outDir, route.path.slice(1), "index.html");
-                await mkdir(path.dirname(outputFile), { recursive: true });
-                await writeFile(outputFile, replaceOutlet(rootHtml, outletFor(compiled, "mpa", route.path)), "utf8");
+            finally {
+                compilation?.abort();
+                releaseRuntimeHooks();
             }
         },
         async handleHotUpdate(context) {
-            if (["/pages/", "/components/", "/layouts/", "/islands/"].some((part) => context.file.includes(part))) {
+            if (nested)
+                return;
+            const file = context.file.replaceAll("\\", "/");
+            if (pageScripts.some(script => script.source === file) || options.serverComponents && (file.endsWith(".fragment.html") || options.serverComponents.references && file.startsWith(path.resolve(vite.root, options.serverComponents.references) + path.sep) || file === path.resolve(vite.root, options.serverComponents.server) || options.serverComponents.client && file === path.resolve(vite.root, options.serverComponents.client)) || ["/pages/", "/components/", "/layouts/", "/islands/", "/api/"].some((part) => file.includes(part))) {
+                const environment = context.environment?.name;
+                if (environment)
+                    invalidateEnvironmentModule(context.server, resolvedVirtualId, environment, environmentApiEnabled);
                 await refresh(context.server);
             }
         }