@tyndall/dev 0.0.1

package/dist/index.js

@@ -0,0 +1,1424 @@
+import { createServer } from "node:http";
+import { copyFile, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { inspect } from "node:util";
+import { CLIENT_ROUTER_BOOTSTRAP_PATH, createRouteGraph, handleDynamicPageApiRequest, loadConfig, renderClientRouterBootstrap, resolvePageModule, resolveRouteWithPolicyFallback, resolveUIAdapter, runGetServerProps, serializeProps, } from "@tyndall/core";
+import { createLogger, computeCacheRootKey, getBunVersion, getOsArch, hash, normalizePath, readFileSafe, resolveCacheRoot, } from "@tyndall/shared";
+import { createDynamicModuleGraphManager, DEFAULT_IMPORT_EXTENSIONS } from "@tyndall/dynamic-graph";
+import { createFileWatcher } from "./watcher.js";
+import { createDevInspector, INSPECTOR_API_PATH, INSPECTOR_PATH, renderInspectorHtml, } from "./inspector.js";
+import { createHmrServer, getHmrClientScript, HMR_CLIENT_PATH, HMR_WS_PATH, } from "./hmr.js";
+export { createFileWatcher } from "./watcher.js";
+export { createHmrServer, getHmrClientScript, HMR_CLIENT_PATH, HMR_WS_PATH } from "./hmr.js";
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+};
+const NAVIGATION_HEADER = "x-hyper-navigation";
+const NAVIGATION_MODE = "csr";
+const DYNAMIC_FALLBACK_HEADER = "x-hyper-dynamic-fallback";
+const RENDER_WARNINGS_HEADER = "x-hyper-render-warnings";
+const DEV_CLIENT_ENTRY_PREFIX = "/_hyper/dev-client";
+const MAX_DEV_CLIENT_ASSET_VERSIONS_PER_ROUTE = 4;
+const DEV_RUNTIME_BUILD_RETRY_COUNT = 2;
+const DEV_RUNTIME_BUILD_RETRY_DELAY_MS = 20;
+const DEV_RUNTIME_DEPENDENCIES = [
+    "react",
+    "react-dom",
+    "scheduler",
+    "react-router",
+    "cookie",
+    "set-cookie-parser",
+    "@tyndall/react",
+];
+const DEV_RUNTIME_ALIAS_CANDIDATES = new Map([
+    ["react", ["react/index.js"]],
+    ["react/jsx-runtime", ["react/jsx-runtime.js"]],
+    ["react/jsx-runtime.js", ["react/jsx-runtime.js"]],
+    ["react/jsx-dev-runtime", ["react/jsx-dev-runtime.js"]],
+    ["react/jsx-dev-runtime.js", ["react/jsx-dev-runtime.js"]],
+    ["react-dom", ["react-dom/index.js"]],
+    ["react-dom/client", ["react-dom/client.js"]],
+    ["react-dom/client.js", ["react-dom/client.js"]],
+    ["react-dom/server", ["react-dom/server.browser.js", "react-dom/server.js"]],
+    ["react-dom/server.js", ["react-dom/server.browser.js", "react-dom/server.js"]],
+    ["react-router", ["react-router/dist/development/index.mjs", "react-router/dist/development/index.js"]],
+    ["@tyndall/react", ["@tyndall/react/src/index.ts", "@tyndall/react/dist/index.js"]],
+    ["scheduler", ["scheduler/index.js"]],
+    ["cookie", ["cookie/dist/index.js", "cookie/index.js"]],
+    ["set-cookie-parser", ["set-cookie-parser/lib/set-cookie.js"]],
+]);
+const DEV_RUNTIME_TRANSIENT_BUILD_PATTERNS = [
+    /EISDIR reading file:/,
+    /Unexpected reading file:/,
+    /EBADF reading file:/,
+    /react\/jsx-dev-runtime\.js/,
+    /ResolveMessage: Could not resolve: "\.\/(?:adapter|components|router|registry|head|head-manager|dynamic-manifest|types|react-router-bridge|islands)\.js"/,
+];
+const resolveFilePath = (root, urlPath) => {
+    const sanitized = urlPath.split("?")[0].split("#")[0];
+    const fullPath = resolve(root, `.${sanitized}`);
+    // Important: block path traversal outside the public directory.
+    if (!fullPath.startsWith(resolve(root))) {
+        return null;
+    }
+    return fullPath;
+};
+const toImportSpecifier = (fromDir, targetPath) => {
+    const normalizedRelative = normalizePath(relative(fromDir, targetPath));
+    if (normalizedRelative.startsWith(".")) {
+        return normalizedRelative;
+    }
+    return `./${normalizedRelative}`;
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const loadRouteGraph = async (routesDir, routeMeta, nestedLayouts) => {
+    try {
+        return await createRouteGraph({
+            routesDir,
+            routeMeta,
+            nestedLayouts,
+        });
+    }
+    catch {
+        return { routes: [] };
+    }
+};
+const HMR_CLIENT_SCRIPT = getHmrClientScript({ wsPath: HMR_WS_PATH });
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\"/g, "&quot;");
+const renderHeadDescriptor = (head) => {
+    const parts = [];
+    if (head.title) {
+        parts.push(`<title>${escapeHtml(head.title)}</title>`);
+    }
+    for (const meta of head.meta ?? []) {
+        const attrs = Object.entries(meta)
+            .map(([key, value]) => `${key}=\"${escapeHtml(String(value))}\"`)
+            .join(" ");
+        parts.push(`<meta ${attrs}>`);
+    }
+    for (const link of head.link ?? []) {
+        const attrs = Object.entries(link)
+            .map(([key, value]) => `${key}=\"${escapeHtml(String(value))}\"`)
+            .join(" ");
+        parts.push(`<link ${attrs}>`);
+    }
+    for (const script of head.script ?? []) {
+        const attrs = Object.entries(script)
+            .map(([key, value]) => `${key}=\"${escapeHtml(String(value))}\"`)
+            .join(" ");
+        parts.push(`<script ${attrs}></script>`);
+    }
+    return parts.join("");
+};
+const renderDevDocument = (input) => {
+    const htmlAttrs = input.ssrPreview ? ' data-hyper-ssr="true"' : "";
+    const buildVersionMeta = input.buildVersion
+        ? `<meta name=\"hyper-build-version\" content=\"${escapeHtml(input.buildVersion)}\">`
+        : "";
+    const buildVersionAttr = input.buildVersion
+        ? ` data-hyper-build-version=\"${escapeHtml(input.buildVersion)}\"`
+        : "";
+    const appAttrs = input.ssrPreview
+        ? ` data-hyper-route=\"${escapeHtml(input.routeId)}\" data-hyper-ssr=\"true\" data-hyper-hydration=\"${input.hydration}\" data-hyper-island-root=\"router\"`
+        : ` data-hyper-route=\"${escapeHtml(input.routeId)}\" data-hyper-hydration=\"${input.hydration}\"`;
+    return [
+        "<!doctype html>",
+        `<html${htmlAttrs}${buildVersionAttr}>`,
+        "<head>",
+        renderHeadDescriptor(input.head),
+        buildVersionMeta,
+        "</head>",
+        "<body>",
+        `<div id=\"app\"${appAttrs}>${input.appHtml}</div>`,
+        `<script id=\"__HYPER_PROPS__\" type=\"application/json\">${input.propsPayload}</script>`,
+        `<script>window.__HYPER_ROUTE_ID__ = ${JSON.stringify(input.routeId)};</script>`,
+        `<script type=\"module\" src=\"${input.clientBootstrapScriptPath}\"></script>`,
+        ...(input.clientRuntimeScriptPath
+            ? [`<script type=\"module\" src=\"${input.clientRuntimeScriptPath}\"></script>`]
+            : []),
+        `<script type=\"module\" src=\"${HMR_CLIENT_PATH}\"></script>`,
+        "</body>",
+        "</html>",
+    ].join("");
+};
+const buildRoutePayload = (rendered) => ({
+    kind: "hyper-route-payload",
+    routeId: rendered.routeId,
+    appHtml: rendered.appHtml,
+    propsPayload: rendered.propsPayload,
+    clientRuntimeScriptPath: rendered.clientRuntimeScriptPath,
+    head: rendered.head,
+    hydration: rendered.hydration,
+});
+const isCsrNavigationRequest = (request) => {
+    const raw = request.headers?.[NAVIGATION_HEADER];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === "string" && value.toLowerCase() === NAVIGATION_MODE;
+};
+const setRenderWarningsHeader = (response, warnings) => {
+    if (!warnings || warnings.length === 0) {
+        return;
+    }
+    response.setHeader(RENDER_WARNINGS_HEADER, warnings.join(" | "));
+};
+const stableParamsKey = (params) => {
+    const entries = Object.keys(params)
+        .sort()
+        .map((key) => [key, params[key]]);
+    return JSON.stringify(entries);
+};
+const getRouteCacheKey = (match) => `${match.route.id}:${stableParamsKey(match.params)}`;
+const normalizeCachePath = (value) => normalizePath(resolve(value));
+const isPathWithinRoot = (rootPath, targetPath) => {
+    const normalizedRoot = normalizeCachePath(rootPath);
+    const normalizedTarget = normalizeCachePath(targetPath);
+    return normalizedTarget === normalizedRoot || normalizedTarget.startsWith(`${normalizedRoot}/`);
+};
+const resolveCacheDir = (rootDir, cacheDir) => isAbsolute(cacheDir) ? cacheDir : resolve(rootDir, cacheDir);
+const resolveHyperVersion = async (rootDir) => {
+    const packagePath = join(rootDir, "packages", "tyndall-core", "package.json");
+    const raw = await readFileSafe(packagePath, "utf-8");
+    const content = raw ? raw.toString() : null;
+    if (!content) {
+        return "unknown";
+    }
+    try {
+        const parsed = JSON.parse(content);
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+};
+const normalizeUrlPath = (value) => value.split("?")[0].split("#")[0];
+const getQueryValue = (url, key) => {
+    try {
+        if (!url) {
+            return null;
+        }
+        const parsed = new URL(url, "http://localhost");
+        return parsed.searchParams.get(key);
+    }
+    catch {
+        return null;
+    }
+};
+const isJavaScriptLike = (filePath) => {
+    const ext = extname(filePath);
+    return ext === ".js" || ext === ".jsx" || ext === ".ts" || ext === ".tsx";
+};
+const isJavaScriptOutputAsset = (filePath) => {
+    const ext = extname(filePath);
+    return ext === ".js" || ext === ".mjs";
+};
+const isRuntimeOutputAsset = (filePath) => {
+    const ext = extname(filePath);
+    return ext === ".js" || ext === ".mjs" || ext === ".css";
+};
+const toPublicUrl = (publicDir, filePath) => {
+    const relativePath = relative(publicDir, filePath);
+    if (!relativePath || relativePath.startsWith("..") || relativePath.includes(`..${sep}`)) {
+        return null;
+    }
+    return `/${relativePath.split(sep).join("/")}`;
+};
+const toErrorInfo = (error) => {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return {
+        message: String(error),
+        stack: undefined,
+    };
+};
+const collectBuildFailureDetails = (error) => {
+    const bundleError = error;
+    const details = [];
+    if (Array.isArray(bundleError.errors) && bundleError.errors.length > 0) {
+        details.push(bundleError.errors.map((value) => String(value)).join(" | "));
+    }
+    if (Array.isArray(bundleError.logs) && bundleError.logs.length > 0) {
+        details.push(bundleError.logs
+            .map((value) => {
+            if (value && typeof value === "object" && "message" in value) {
+                const message = value.message;
+                if (typeof message === "string" && message.length > 0) {
+                    return message;
+                }
+            }
+            return inspect(value, { depth: 2 });
+        })
+            .join(" | "));
+    }
+    if (bundleError.cause) {
+        details.push(String(bundleError.cause));
+    }
+    if (details.length === 0) {
+        details.push(inspect(error, { depth: 3 }));
+    }
+    return details;
+};
+const isTransientRuntimeBuildFailure = (details) => details.some((detail) => DEV_RUNTIME_TRANSIENT_BUILD_PATTERNS.some((pattern) => pattern.test(detail)));
+const getBunBuildApi = () => {
+    const runtime = globalThis;
+    if (runtime.Bun && typeof runtime.Bun.build === "function") {
+        return { build: runtime.Bun.build };
+    }
+    return null;
+};
+export const startDevServer = async (options = {}) => {
+    const host = options.host ?? "localhost";
+    const port = options.port ?? 3000;
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = await loadConfig(rootDir);
+    const buildVersion = config.build.version.trim();
+    // SSR preview is allowed only when both --ssr and config.ssr are enabled.
+    const ssrPreviewEnabled = Boolean(options.ssr) && config.ssr;
+    const ssrClientRoutingEnabled = ssrPreviewEnabled && config.routing.ssrClientRouting;
+    const logger = options.logger ??
+        createLogger({
+            level: config.logging?.level ?? "info",
+            prefix: "hyper:dev",
+        });
+    const clientBootstrapScript = renderClientRouterBootstrap({
+        navigationMode: ssrClientRoutingEnabled ? "client" : config.routing.navigation,
+        clientRenderMode: config.routing.clientRender,
+        linkInterceptionMode: ssrClientRoutingEnabled ? "all" : "marked",
+    });
+    const routesDir = options.routesDir ?? config.routesDir;
+    const publicDir = options.publicDir ?? config.publicDir;
+    const resolvedRootDir = resolve(rootDir);
+    const resolvedRoutesDir = resolve(rootDir, routesDir);
+    const resolvedPublicDir = resolve(rootDir, publicDir);
+    const normalizedRoutesDir = normalizeCachePath(resolvedRoutesDir);
+    const normalizedPublicDir = normalizeCachePath(resolvedPublicDir);
+    const normalizedRootDir = normalizeCachePath(resolvedRootDir);
+    const normalizedNodeModulesDir = normalizeCachePath(join(resolvedRootDir, "node_modules"));
+    const normalizedGitDir = normalizeCachePath(join(resolvedRootDir, ".git"));
+    const cacheDir = resolveCacheDir(rootDir, config.cache.dir);
+    const normalizedCacheDir = normalizeCachePath(cacheDir);
+    const normalizedInternalDir = normalizeCachePath(resolve(rootDir, ".hyper"));
+    const normalizedOutDir = normalizeCachePath(resolve(rootDir, config.outDir));
+    const ignoredRouteGraphRoots = [
+        normalizedNodeModulesDir,
+        normalizedGitDir,
+        normalizedInternalDir,
+        normalizedOutDir,
+        normalizedCacheDir,
+    ];
+    const isIgnoredRouteGraphPath = (targetPath) => ignoredRouteGraphRoots.some((ignoredRoot) => isPathWithinRoot(ignoredRoot, targetPath));
+    const filterRouteGraph = (graph) => ({
+        routes: graph.routes.filter((route) => !isIgnoredRouteGraphPath(route.filePath)),
+    });
+    let routeGraph = filterRouteGraph(await loadRouteGraph(resolvedRoutesDir, config.routing.routeMeta, config.routing.nestedLayouts));
+    const inspector = createDevInspector();
+    const prefetchPath = options.prefetchPath ?? "/__hyper/prefetch";
+    const routeCache = new Map();
+    const buildRouteIndex = (graph) => {
+        const byId = new Map();
+        const byFile = new Map();
+        for (const route of graph.routes) {
+            byId.set(route.id, route);
+            byFile.set(normalizeCachePath(route.filePath), route);
+        }
+        return { byId, byFile };
+    };
+    const buildLayoutIndex = (graph) => {
+        const byFile = new Map();
+        for (const route of graph.routes) {
+            for (const layoutFile of route.layoutFiles ?? []) {
+                const key = normalizeCachePath(layoutFile);
+                const routes = byFile.get(key) ?? new Set();
+                routes.add(route.id);
+                byFile.set(key, routes);
+            }
+        }
+        return { byFile };
+    };
+    let routeIndex = buildRouteIndex(routeGraph);
+    let layoutIndex = buildLayoutIndex(routeGraph);
+    const setRouteGraph = (graph) => {
+        routeGraph = graph;
+        routeIndex = buildRouteIndex(graph);
+        layoutIndex = buildLayoutIndex(graph);
+    };
+    const uiAdapter = typeof config.ui.adapter === "string"
+        ? config.ui.adapter
+        : (config.ui.adapter?.name ?? "custom");
+    const hyperVersion = config.cache.enabled ? await resolveHyperVersion(rootDir) : "disabled";
+    const rootKey = config.cache.enabled
+        ? computeCacheRootKey({
+            projectId: normalizeCachePath(rootDir),
+            hyperVersion,
+            bunVersion: getBunVersion(),
+            uiAdapter,
+            osArch: getOsArch(),
+        })
+        : "disabled";
+    // Important: cacheRoot keeps dev caches separated per project/toolchain.
+    const cacheRoot = config.cache.enabled ? resolveCacheRoot(cacheDir, rootKey) : cacheDir;
+    // Keep runtime deps out of cacheRoot/node_modules so server renders resolve React from the app tree.
+    const runtimeNodeModulesDir = join(cacheRoot, "runtime-node-modules");
+    const legacyRuntimeNodeModulesDir = join(cacheRoot, "node_modules");
+    await rm(legacyRuntimeNodeModulesDir, { recursive: true, force: true }).catch(() => { });
+    let runtimeNodeModulesReady = null;
+    let runtimeDependencyAliasMapReady = null;
+    const findRuntimeDependency = async (startDir, dependencyName) => {
+        let current = resolve(startDir);
+        while (true) {
+            const candidate = join(current, "node_modules", dependencyName);
+            const exists = await stat(candidate)
+                .then(() => true)
+                .catch(() => false);
+            if (exists) {
+                return candidate;
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                return undefined;
+            }
+            current = parent;
+        }
+    };
+    const ensureRuntimeNodeModules = async () => {
+        if (runtimeNodeModulesReady) {
+            await runtimeNodeModulesReady;
+            return;
+        }
+        runtimeNodeModulesReady = (async () => {
+            const legacyExists = await stat(legacyRuntimeNodeModulesDir)
+                .then(() => true)
+                .catch(() => false);
+            if (legacyExists) {
+                await rm(legacyRuntimeNodeModulesDir, { recursive: true, force: true });
+            }
+            await mkdir(runtimeNodeModulesDir, { recursive: true });
+            for (const dependencyName of DEV_RUNTIME_DEPENDENCIES) {
+                const targetPath = join(runtimeNodeModulesDir, dependencyName);
+                const sourceRoots = [resolvedRootDir, process.cwd()].filter((value, index, list) => list.indexOf(value) === index);
+                let sourcePath;
+                for (const root of sourceRoots) {
+                    sourcePath = await findRuntimeDependency(root, dependencyName);
+                    if (sourcePath) {
+                        break;
+                    }
+                }
+                if (!sourcePath) {
+                    const searched = sourceRoots.map((root) => join(root, "node_modules", dependencyName));
+                    throw new Error(`Missing dev runtime dependency "${dependencyName}" in ${searched.join(", ")}.`);
+                }
+                // Bun dev runtime bundling is unstable with symlinked workspace dependencies,
+                // so we materialize concrete package trees inside cacheRoot/runtime-node-modules.
+                await cp(sourcePath, targetPath, {
+                    recursive: true,
+                    dereference: true,
+                    force: true,
+                });
+            }
+        })();
+        await runtimeNodeModulesReady;
+    };
+    const ensureRuntimeDependencyAliasMap = async () => {
+        if (runtimeDependencyAliasMapReady) {
+            return runtimeDependencyAliasMapReady;
+        }
+        runtimeDependencyAliasMapReady = (async () => {
+            await ensureRuntimeNodeModules();
+            const aliasMap = new Map();
+            for (const [specifier, candidates] of DEV_RUNTIME_ALIAS_CANDIDATES.entries()) {
+                for (const relativeCandidate of candidates) {
+                    const candidatePath = join(runtimeNodeModulesDir, relativeCandidate);
+                    const candidateIsFile = await stat(candidatePath)
+                        .then((result) => result.isFile())
+                        .catch(() => false);
+                    if (!candidateIsFile) {
+                        continue;
+                    }
+                    aliasMap.set(specifier, candidatePath);
+                    break;
+                }
+            }
+            return aliasMap;
+        })();
+        return runtimeDependencyAliasMapReady;
+    };
+    const dynamicGraph = createDynamicModuleGraphManager({
+        extensions: DEFAULT_IMPORT_EXTENSIONS,
+    });
+    for (const route of routeGraph.routes) {
+        dynamicGraph.registerEntry({ entryId: route.id, filePath: route.filePath });
+    }
+    const routeHits = new Set();
+    const routeRenderVersion = new Map();
+    const routeRenderDirectories = new Map();
+    const inflightRouteRenders = new Map();
+    const devClientAssets = new Map();
+    const routeClientAssetVersions = new Map();
+    let runtimeBuildQueue = Promise.resolve();
+    const runSerializedRuntimeBuild = async (buildTask) => {
+        const pending = runtimeBuildQueue.then(buildTask, buildTask);
+        runtimeBuildQueue = pending.then(() => undefined, () => undefined);
+        return pending;
+    };
+    let hyperCoreBrowserShimSource = null;
+    const resolveCoreShimModulePath = async (entryDir, moduleName) => {
+        const candidates = [
+            `${moduleName}.js`,
+            `${moduleName}.mjs`,
+            `${moduleName}.cjs`,
+            `${moduleName}.ts`,
+            `${moduleName}.tsx`,
+        ];
+        for (const candidate of candidates) {
+            const candidatePath = join(entryDir, candidate);
+            const exists = await stat(candidatePath)
+                .then((result) => result.isFile())
+                .catch(() => false);
+            if (exists) {
+                return candidatePath;
+            }
+        }
+        throw new Error(`Missing core shim module "${moduleName}" in ${entryDir}.`);
+    };
+    const resolveHyperCoreBrowserShimSource = async () => {
+        if (hyperCoreBrowserShimSource) {
+            return hyperCoreBrowserShimSource;
+        }
+        const resolver = import.meta;
+        if (typeof resolver.resolve !== "function") {
+            throw new Error("import.meta.resolve is unavailable while building dev client runtime.");
+        }
+        const resolvedEntry = await resolver.resolve("@tyndall/core");
+        const entryPath = resolvedEntry.startsWith("file://")
+            ? fileURLToPath(resolvedEntry)
+            : resolvedEntry;
+        const entryDir = dirname(entryPath);
+        const headPath = await resolveCoreShimModulePath(entryDir, "head");
+        const propsPath = await resolveCoreShimModulePath(entryDir, "props");
+        const renderPolicyPath = await resolveCoreShimModulePath(entryDir, "render-policy");
+        const resolverFallbackPath = await resolveCoreShimModulePath(entryDir, "resolver-fallback");
+        hyperCoreBrowserShimSource = [
+            `export { mergeHeadDescriptors } from ${JSON.stringify(headPath)};`,
+            `export { serializeProps } from ${JSON.stringify(propsPath)};`,
+            `export { evaluateRenderPolicy } from ${JSON.stringify(renderPolicyPath)};`,
+            `export { shouldForceDynamicFallback } from ${JSON.stringify(resolverFallbackPath)};`,
+        ].join("\n");
+        return hyperCoreBrowserShimSource;
+    };
+    const getRouteAssetPrefix = (routeId) => `${DEV_CLIENT_ENTRY_PREFIX}/${hash(routeId).slice(0, 10)}/`;
+    const getRouteAssetVersionPrefix = (routeId, version) => `${getRouteAssetPrefix(routeId)}${version}/`;
+    const removeDevClientAssetsByRouteVersion = (routeId, version) => {
+        const prefix = getRouteAssetVersionPrefix(routeId, version);
+        for (const assetPath of Array.from(devClientAssets.keys())) {
+            if (assetPath.startsWith(prefix)) {
+                devClientAssets.delete(assetPath);
+            }
+        }
+    };
+    const removeDevClientAssetsByRoute = (routeId) => {
+        const prefix = getRouteAssetPrefix(routeId);
+        for (const assetPath of Array.from(devClientAssets.keys())) {
+            if (assetPath.startsWith(prefix)) {
+                devClientAssets.delete(assetPath);
+            }
+        }
+        routeClientAssetVersions.delete(routeId);
+    };
+    const trackRouteAssetVersion = (routeId, version) => {
+        const nextVersions = [
+            ...(routeClientAssetVersions.get(routeId) ?? []).filter((item) => item !== version),
+            version,
+        ].sort((left, right) => right - left);
+        routeClientAssetVersions.set(routeId, nextVersions);
+    };
+    const pruneStaleRouteAssetVersions = (routeId) => {
+        const versions = routeClientAssetVersions.get(routeId);
+        if (!versions || versions.length <= MAX_DEV_CLIENT_ASSET_VERSIONS_PER_ROUTE) {
+            return;
+        }
+        const retained = versions.slice(0, MAX_DEV_CLIENT_ASSET_VERSIONS_PER_ROUTE);
+        const stale = versions.slice(MAX_DEV_CLIENT_ASSET_VERSIONS_PER_ROUTE);
+        routeClientAssetVersions.set(routeId, retained);
+        for (const version of stale) {
+            removeDevClientAssetsByRouteVersion(routeId, version);
+        }
+    };
+    const registerRouteHit = (route) => {
+        routeHits.add(route.id);
+        dynamicGraph.registerEntry({ entryId: route.id, filePath: route.filePath });
+    };
+    const resolveAdapterForRoute = (route, loaded, pageRender, pageHead) => resolveUIAdapter(config.ui.adapter, {
+        ...config.ui.options,
+        navigationMode: config.routing.navigation,
+        clientRenderMode: config.routing.clientRender,
+        nestedLayouts: config.routing.nestedLayouts,
+        routeGraph,
+        rootDir: resolvedRootDir,
+        routeRoot: loaded.routeRoot,
+        routeRender: pageRender,
+        routeHead: pageHead,
+    }, options.adapterRegistry);
+    const resolveRouteModulesForRender = (route) => {
+        const modules = dynamicGraph.ensureEntryGraph({
+            entryId: route.id,
+            filePath: route.filePath,
+        });
+        const normalizedModules = new Set(modules.map((modulePath) => normalizeCachePath(modulePath)));
+        normalizedModules.add(normalizeCachePath(route.filePath));
+        for (const layoutFile of route.layoutFiles ?? []) {
+            normalizedModules.add(normalizeCachePath(layoutFile));
+        }
+        return normalizedModules;
+    };
+    const shouldCopyRouteSnapshotModule = (modulePath) => {
+        if (!isPathWithinRoot(resolvedRootDir, modulePath)) {
+            return false;
+        }
+        if (isPathWithinRoot(normalizedNodeModulesDir, modulePath)) {
+            return false;
+        }
+        if (isPathWithinRoot(normalizedInternalDir, modulePath)) {
+            return false;
+        }
+        if (isPathWithinRoot(normalizedOutDir, modulePath)) {
+            return false;
+        }
+        return true;
+    };
+    const loadRouteModule = async (route) => {
+        const modules = resolveRouteModulesForRender(route);
+        const localModules = Array.from(modules).filter((modulePath) => shouldCopyRouteSnapshotModule(modulePath));
+        if (localModules.length === 0) {
+            return {
+                module: await import(`${pathToFileURL(route.filePath).href}?dev=${Date.now()}`),
+            };
+        }
+        const version = (routeRenderVersion.get(route.id) ?? 0) + 1;
+        routeRenderVersion.set(route.id, version);
+        const routeRoot = join(cacheRoot, "dev-route-modules", hash(route.id).slice(0, 10), String(version));
+        await mkdir(routeRoot, { recursive: true });
+        for (const modulePath of localModules) {
+            const relativePath = relative(resolvedRootDir, modulePath);
+            if (!relativePath || relativePath.startsWith(`..${sep}`) || relativePath === "..") {
+                continue;
+            }
+            const targetPath = join(routeRoot, relativePath);
+            await mkdir(dirname(targetPath), { recursive: true });
+            await copyFile(modulePath, targetPath);
+        }
+        const routeRelativePath = relative(resolvedRootDir, route.filePath);
+        if (!routeRelativePath ||
+            routeRelativePath === ".." ||
+            routeRelativePath.startsWith(`..${sep}`)) {
+            return {
+                module: await import(`${pathToFileURL(route.filePath).href}?dev=${Date.now()}`),
+            };
+        }
+        const copiedEntryPath = join(routeRoot, routeRelativePath);
+        // Keep versioned snapshots for the active dev session; deleting previous snapshots eagerly
+        // can race with in-flight imports/builds from concurrent prefetch requests.
+        const routeVersions = routeRenderDirectories.get(route.id) ?? new Map();
+        routeVersions.set(version, routeRoot);
+        routeRenderDirectories.set(route.id, routeVersions);
+        return {
+            module: await import(pathToFileURL(copiedEntryPath).href),
+            routeRoot,
+            routeRelativePath,
+            version,
+        };
+    };
+    const buildClientRuntimeScript = async (route, loaded, adapter) => {
+        if (!loaded.routeRoot || !loaded.routeRelativePath || loaded.version === undefined) {
+            return undefined;
+        }
+        if (typeof adapter.createClientEntry !== "function") {
+            return undefined;
+        }
+        const routeRoot = loaded.routeRoot;
+        const pageModule = `./${loaded.routeRelativePath.split(sep).join("/")}`;
+        const routeModuleMap = routeGraph.routes.reduce((acc, routeRecord) => {
+            acc[routeRecord.id] = toImportSpecifier(routeRoot, routeRecord.filePath);
+            return acc;
+        }, {});
+        const entrySource = adapter.createClientEntry({
+            routeId: route.id,
+            routeGraph,
+            rootDir: resolvedRootDir,
+            entryDir: routeRoot,
+            routeRoot,
+            uiOptions: {
+                ...config.ui.options,
+                pageModule,
+                navigationMode: config.routing.navigation,
+                clientRenderMode: config.routing.clientRender,
+                clientRouteModules: routeModuleMap,
+                nestedLayouts: config.routing.nestedLayouts,
+            },
+            adapterOptions: {
+                ...config.ui.options,
+                pageModule,
+                navigationMode: config.routing.navigation,
+                clientRenderMode: config.routing.clientRender,
+                clientRouteModules: routeModuleMap,
+                nestedLayouts: config.routing.nestedLayouts,
+            },
+        });
+        if (typeof entrySource !== "string" || entrySource.trim().length === 0) {
+            return undefined;
+        }
+        const entryFilePath = join(loaded.routeRoot, "__hyper_client_entry.tsx");
+        const outDir = join(loaded.routeRoot, "__hyper_client_bundle");
+        await mkdir(outDir, { recursive: true });
+        await writeFile(entryFilePath, entrySource, "utf-8");
+        const bun = getBunBuildApi();
+        if (!bun) {
+            throw new Error("Bun.build API is unavailable while generating dev client runtime.");
+        }
+        const hyperCoreShim = await resolveHyperCoreBrowserShimSource();
+        const runtimeDependencyAliasMap = await ensureRuntimeDependencyAliasMap();
+        const runtimeDependencyAliasSpecifiers = Array.from(runtimeDependencyAliasMap.keys()).sort((left, right) => right.length - left.length);
+        const runtimeDependencyAliasPattern = runtimeDependencyAliasSpecifiers.length > 0
+            ? new RegExp(`^(?:${runtimeDependencyAliasSpecifiers.map((specifier) => escapeRegExp(specifier)).join("|")})$`)
+            : null;
+        const plugins = [
+            {
+                name: "@tyndall/core-browser-shim",
+                setup(build) {
+                    build.onResolve({ filter: /^@tyndall\/core$/ }, () => ({
+                        path: "@tyndall/core-browser-shim",
+                        namespace: "@tyndall/core-browser-shim",
+                    }));
+                    build.onLoad({ filter: /^@tyndall\/core-browser-shim$/, namespace: "@tyndall/core-browser-shim" }, () => ({
+                        contents: hyperCoreShim,
+                        loader: "js",
+                    }));
+                },
+            },
+            ...(runtimeDependencyAliasPattern
+                ? [
+                    {
+                        name: "@tyndall/runtime-dependency-alias",
+                        setup(build) {
+                            build.onResolve({
+                                filter: runtimeDependencyAliasPattern,
+                            }, ({ path }) => {
+                                const resolvedPath = runtimeDependencyAliasMap.get(path);
+                                if (!resolvedPath) {
+                                    return;
+                                }
+                                return { path: resolvedPath };
+                            });
+                        },
+                    },
+                ]
+                : []),
+        ];
+        let buildResult;
+        for (let attempt = 0; attempt <= DEV_RUNTIME_BUILD_RETRY_COUNT; attempt += 1) {
+            try {
+                const candidate = await runSerializedRuntimeBuild(() => bun.build({
+                    entrypoints: [entryFilePath],
+                    outdir: outDir,
+                    root: loaded.routeRoot,
+                    target: "browser",
+                    format: "esm",
+                    splitting: true,
+                    sourcemap: "inline",
+                    minify: false,
+                    plugins,
+                }));
+                if (!candidate.success) {
+                    const errors = (candidate.logs ?? [])
+                        .map((log) => log.message)
+                        .filter((message) => typeof message === "string" && message.length > 0);
+                    if (attempt < DEV_RUNTIME_BUILD_RETRY_COUNT &&
+                        isTransientRuntimeBuildFailure(errors)) {
+                        await new Promise((resolveRetry) => setTimeout(resolveRetry, DEV_RUNTIME_BUILD_RETRY_DELAY_MS * (attempt + 1)));
+                        continue;
+                    }
+                    throw new Error(`Failed to build dev client runtime for route "${route.id}".${errors.length > 0 ? ` ${errors.join(" | ")}` : ""}`);
+                }
+                buildResult = candidate;
+                break;
+            }
+            catch (error) {
+                const info = toErrorInfo(error);
+                if (attempt < DEV_RUNTIME_BUILD_RETRY_COUNT &&
+                    isTransientRuntimeBuildFailure([info.message])) {
+                    await new Promise((resolveRetry) => setTimeout(resolveRetry, DEV_RUNTIME_BUILD_RETRY_DELAY_MS * (attempt + 1)));
+                    continue;
+                }
+                const details = collectBuildFailureDetails(error);
+                throw new Error(`Failed to build dev client runtime for route "${route.id}" (entry: ${entryFilePath}). ${details.join(" || ")}`);
+            }
+        }
+        if (!buildResult?.success) {
+            throw new Error(`Failed to build dev client runtime for route "${route.id}" after ${DEV_RUNTIME_BUILD_RETRY_COUNT + 1} attempts.`);
+        }
+        const outputAssets = (buildResult.outputs ?? [])
+            .map((artifact) => artifact.path)
+            .filter((path) => typeof path === "string" && isRuntimeOutputAsset(path) && isPathWithinRoot(outDir, path));
+        if (outputAssets.length === 0) {
+            throw new Error(`Dev client runtime output is missing for route "${route.id}".`);
+        }
+        const assetPrefix = `${getRouteAssetPrefix(route.id)}${loaded.version}/`;
+        let scriptPath;
+        for (const outputPath of outputAssets) {
+            const relativeOutputPath = normalizePath(relative(outDir, outputPath));
+            if (relativeOutputPath.length === 0 ||
+                relativeOutputPath.startsWith("..") ||
+                relativeOutputPath.includes("/../")) {
+                continue;
+            }
+            const publicPath = `${assetPrefix}${relativeOutputPath}`;
+            devClientAssets.set(publicPath, outputPath);
+            if (!scriptPath &&
+                isJavaScriptOutputAsset(outputPath) &&
+                (relativeOutputPath === "__hyper_client_entry.js" ||
+                    relativeOutputPath === "__hyper_client_entry.mjs")) {
+                scriptPath = publicPath;
+            }
+        }
+        if (!scriptPath) {
+            const fallbackScript = outputAssets
+                .filter((outputPath) => isJavaScriptOutputAsset(outputPath))
+                .sort((left, right) => left.localeCompare(right))[0];
+            if (!fallbackScript) {
+                throw new Error(`Dev client runtime script output is missing for route "${route.id}".`);
+            }
+            const relativeOutputPath = normalizePath(relative(outDir, fallbackScript));
+            scriptPath = `${assetPrefix}${relativeOutputPath}`;
+        }
+        trackRouteAssetVersion(route.id, loaded.version);
+        pruneStaleRouteAssetVersions(route.id);
+        return scriptPath;
+    };
+    const renderRoute = async (match, request, response) => {
+        const loaded = await loadRouteModule(match.route);
+        const page = resolvePageModule(loaded.module);
+        const adapter = resolveAdapterForRoute(match.route, loaded, (props) => page.default(props), page.head ? (props) => page.head?.(props) ?? {} : undefined);
+        if (typeof adapter.renderToHtml !== "function") {
+            throw new Error(`UI adapter "${adapter.name}" does not support renderToHtml.`);
+        }
+        // Run server props in dev whenever the route exports it so page contracts stay consistent.
+        const serverProps = page.getServerProps
+            ? await runGetServerProps(page.getServerProps, {
+                routeId: match.route.id,
+                params: match.params,
+                request,
+                response,
+            })
+            : null;
+        const props = serverProps?.props ?? {};
+        const rendered = await adapter.renderToHtml({
+            routeId: match.route.id,
+            params: match.params,
+            props,
+        });
+        const payload = adapter.serializeProps?.(props) ?? serializeProps(props);
+        let clientRuntimeScriptPath;
+        try {
+            clientRuntimeScriptPath = await buildClientRuntimeScript(match.route, loaded, adapter);
+        }
+        catch (error) {
+            const info = toErrorInfo(error);
+            logger.warn("Dev client runtime build failed; falling back to bootstrap-only mode", {
+                routeId: match.route.id,
+                message: info.message,
+            });
+        }
+        const hydration = ssrPreviewEnabled ? "islands" : "full";
+        const html = renderDevDocument({
+            routeId: match.route.id,
+            appHtml: rendered.html,
+            head: rendered.head ?? {},
+            propsPayload: payload,
+            ssrPreview: ssrPreviewEnabled,
+            hydration,
+            clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
+            clientRuntimeScriptPath,
+            buildVersion,
+        });
+        return {
+            html,
+            routeId: match.route.id,
+            appHtml: rendered.html,
+            head: rendered.head ?? {},
+            propsPayload: payload,
+            clientRuntimeScriptPath,
+            hydration,
+            status: rendered.status ?? serverProps?.status ?? 200,
+            headers: {
+                ...(serverProps?.headers ?? {}),
+                ...(rendered.headers ?? {}),
+            },
+        };
+    };
+    const invalidateRoutesById = (routeIds) => {
+        for (const routeId of routeIds) {
+            for (const key of routeCache.keys()) {
+                if (key.startsWith(`${routeId}:`)) {
+                    routeCache.delete(key);
+                }
+            }
+        }
+    };
+    const refreshRouteGraphForChanges = async (changedPaths) => {
+        const shouldReload = changedPaths.some((changedPath) => changedPath.startsWith(normalizedRoutesDir) && !isIgnoredRouteGraphPath(changedPath));
+        if (!shouldReload) {
+            return {
+                added: [],
+                removed: [],
+                changed: [],
+            };
+        }
+        const nextGraph = filterRouteGraph(await loadRouteGraph(resolvedRoutesDir, config.routing.routeMeta, config.routing.nestedLayouts));
+        const previousById = routeIndex.byId;
+        const nextIndex = buildRouteIndex(nextGraph);
+        const added = [];
+        const removed = [];
+        const changed = [];
+        for (const [routeId, nextRoute] of nextIndex.byId.entries()) {
+            const previous = previousById.get(routeId);
+            if (!previous) {
+                added.push(nextRoute);
+                continue;
+            }
+            if (normalizeCachePath(previous.filePath) !== normalizeCachePath(nextRoute.filePath)) {
+                changed.push(nextRoute);
+            }
+        }
+        for (const [routeId, previousRoute] of previousById.entries()) {
+            if (!nextIndex.byId.has(routeId)) {
+                removed.push(previousRoute);
+            }
+        }
+        setRouteGraph(nextGraph);
+        return { added, removed, changed };
+    };
+    const refreshDynamicGraphForChanges = async (changedPaths) => {
+        const normalizedChangedPaths = changedPaths.map((path) => normalizeCachePath(path));
+        const hasDirectoryScopeChange = normalizedChangedPaths.some((changedPath) => changedPath === normalizedRootDir ||
+            changedPath === normalizedRoutesDir ||
+            changedPath === normalizedPublicDir);
+        const needsFullClear = normalizedChangedPaths.some((changedPath) => {
+            if (hasDirectoryScopeChange) {
+                return true;
+            }
+            if (!changedPath.startsWith(normalizedRootDir)) {
+                return false;
+            }
+            if (changedPath.startsWith(normalizedPublicDir) && extname(changedPath) === ".css") {
+                return false;
+            }
+            return !isJavaScriptLike(changedPath);
+        });
+        const impactedRoutes = new Set();
+        const changeResult = dynamicGraph.applyFileChanges(normalizedChangedPaths);
+        for (const routeId of changeResult.impactedEntryIds) {
+            impactedRoutes.add(routeId);
+        }
+        for (const changedPath of normalizedChangedPaths) {
+            const directRoute = routeIndex.byFile.get(changedPath);
+            if (directRoute) {
+                impactedRoutes.add(directRoute.id);
+            }
+            const layoutRoutes = layoutIndex.byFile.get(changedPath);
+            if (layoutRoutes) {
+                for (const routeId of layoutRoutes) {
+                    impactedRoutes.add(routeId);
+                }
+            }
+        }
+        if (hasDirectoryScopeChange && impactedRoutes.size === 0) {
+            for (const routeId of routeHits) {
+                impactedRoutes.add(routeId);
+            }
+        }
+        for (const routeId of impactedRoutes) {
+            const route = routeIndex.byId.get(routeId);
+            if (!route || !routeHits.has(routeId)) {
+                continue;
+            }
+            dynamicGraph.ensureEntryGraph({ entryId: routeId, filePath: route.filePath });
+        }
+        // Invalidate cache before async route-graph refresh so manual `server.invalidate()` calls apply immediately.
+        if (needsFullClear) {
+            routeCache.clear();
+            devClientAssets.clear();
+            routeClientAssetVersions.clear();
+        }
+        else {
+            invalidateRoutesById(impactedRoutes);
+        }
+        const { added, removed, changed } = await refreshRouteGraphForChanges(normalizedChangedPaths);
+        for (const removedRoute of removed) {
+            impactedRoutes.add(removedRoute.id);
+            dynamicGraph.removeEntry(removedRoute.id);
+            routeHits.delete(removedRoute.id);
+            removeDevClientAssetsByRoute(removedRoute.id);
+        }
+        for (const route of [...added, ...changed]) {
+            dynamicGraph.registerEntry({ entryId: route.id, filePath: route.filePath });
+            impactedRoutes.add(route.id);
+            if (routeHits.has(route.id)) {
+                dynamicGraph.ensureEntryGraph({ entryId: route.id, filePath: route.filePath });
+            }
+        }
+        if (!needsFullClear) {
+            invalidateRoutesById(impactedRoutes);
+        }
+        const hmrRoutes = Array.from(impactedRoutes)
+            .filter((routeId) => routeHits.has(routeId))
+            .sort((left, right) => left.localeCompare(right));
+        return {
+            normalizedChangedPaths,
+            hmrRoutes,
+        };
+    };
+    const server = createServer(async (request, response) => {
+        const urlPath = normalizeUrlPath(request.url ?? "/");
+        const requestUrl = new URL(request.url ?? "/", "http://localhost");
+        const startedAt = process.hrtime.bigint();
+        let routeId;
+        let kind = "unknown";
+        // Use `finish` to capture total time including async IO and response flush.
+        response.on("finish", () => {
+            const durationMs = Number(process.hrtime.bigint() - startedAt) / 1000000;
+            inspector.recordRequest({
+                method: request.method ?? "GET",
+                path: urlPath,
+                status: response.statusCode,
+                durationMs,
+                routeId,
+                kind,
+            });
+        });
+        const resolveRouteForRequest = (pathname) => resolveRouteWithPolicyFallback({
+            pathname,
+            routeGraph,
+            appMode: config.mode,
+            policy: options.fallbackPolicy,
+            dynamicResolver: options.dynamicPageApi
+                ? (path) => options.dynamicPageApi?.resolveByPath({
+                    path,
+                    locale: requestUrl.searchParams.get("locale") ?? undefined,
+                    variant: requestUrl.searchParams.get("variant") ?? undefined,
+                    device: requestUrl.searchParams.get("device") ?? undefined,
+                    ctxHash: requestUrl.searchParams.get("ctxHash") ?? undefined,
+                }) ?? Promise.resolve(null)
+                : undefined,
+        });
+        const respondWithResolvedRoute = async (resolved, pathname) => {
+            if (resolved.type === "file") {
+                await respondWithRoute(resolved.match);
+                return true;
+            }
+            if (resolved.type === "redirect") {
+                kind = "route";
+                routeId = pathname;
+                response.statusCode = 307;
+                response.setHeader("location", resolved.location);
+                response.end();
+                return true;
+            }
+            if (resolved.type === "dynamic") {
+                kind = "route";
+                routeId = pathname;
+                setRenderWarningsHeader(response, resolved.warnings);
+                if (resolved.mode === "ssr") {
+                    response.statusCode = 501;
+                    response.setHeader("content-type", "text/plain; charset=utf-8");
+                    response.end("Dynamic SSR fallback is not implemented in dev server.");
+                    return true;
+                }
+                if (isCsrNavigationRequest(request)) {
+                    response.statusCode = 204;
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.setHeader(DYNAMIC_FALLBACK_HEADER, "csr");
+                    response.end();
+                    return true;
+                }
+                response.statusCode = 200;
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                response.end(renderDevDocument({
+                    routeId: pathname,
+                    appHtml: `<main data-hyper-dynamic=\"true\">Dynamic Route: ${escapeHtml(pathname)}</main>`,
+                    head: { title: `Dynamic ${pathname}` },
+                    propsPayload: serializeProps({}),
+                    ssrPreview: ssrPreviewEnabled,
+                    hydration: ssrPreviewEnabled ? "islands" : "full",
+                    clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
+                    buildVersion,
+                }));
+                return true;
+            }
+            return false;
+        };
+        const respondWithRoute = async (match) => {
+            kind = "route";
+            routeId = match.route.id;
+            const navigationRequest = isCsrNavigationRequest(request);
+            registerRouteHit(match.route);
+            const cacheKey = getRouteCacheKey(match);
+            const cached = routeCache.get(cacheKey);
+            if (cached) {
+                response.statusCode = cached.status;
+                for (const [header, value] of Object.entries(cached.headers)) {
+                    response.setHeader(header, value);
+                }
+                if (navigationRequest) {
+                    response.setHeader("content-type", "application/json; charset=utf-8");
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.setHeader("x-hyper-route-cache", "hit");
+                    response.end(JSON.stringify(buildRoutePayload(cached)));
+                    return;
+                }
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                response.setHeader("x-hyper-route-cache", "hit");
+                response.end(cached.html);
+                return;
+            }
+            try {
+                let renderedPromise = inflightRouteRenders.get(cacheKey);
+                if (!renderedPromise) {
+                    // Deduplicate concurrent renders for the same route cache key to avoid duplicate
+                    // module snapshot/build work and transient file-system races.
+                    const routeRenderPromise = renderRoute(match, request, response);
+                    const trackedRouteRenderPromise = routeRenderPromise.finally(() => {
+                        if (inflightRouteRenders.get(cacheKey) === trackedRouteRenderPromise) {
+                            inflightRouteRenders.delete(cacheKey);
+                        }
+                    });
+                    inflightRouteRenders.set(cacheKey, trackedRouteRenderPromise);
+                    renderedPromise = trackedRouteRenderPromise;
+                }
+                const rendered = await renderedPromise;
+                response.statusCode = rendered.status;
+                for (const [header, value] of Object.entries(rendered.headers)) {
+                    response.setHeader(header, value);
+                }
+                routeCache.set(cacheKey, { ...rendered, updatedAt: Date.now() });
+                if (navigationRequest) {
+                    response.setHeader("content-type", "application/json; charset=utf-8");
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.setHeader("x-hyper-route-cache", "miss");
+                    response.end(JSON.stringify(buildRoutePayload(rendered)));
+                    return;
+                }
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                response.setHeader("x-hyper-route-cache", "miss");
+                response.end(rendered.html);
+            }
+            catch (error) {
+                const { message, stack } = toErrorInfo(error);
+                logger.error("Route render failed", {
+                    routeId: match.route.id,
+                    path: request.url ?? "/",
+                    message,
+                });
+                if (stack) {
+                    logger.error("Route render stack", {
+                        routeId: match.route.id,
+                        stack,
+                    });
+                }
+                hmr.broadcastError(message, stack);
+                response.statusCode = 500;
+                response.setHeader("x-hyper-route-cache", "miss");
+                response.end(renderDevDocument({
+                    routeId: match.route.id,
+                    appHtml: `<main><h1>Dev Render Error</h1><pre>${escapeHtml(message)}</pre></main>`,
+                    head: { title: `Dev Error ${match.route.id}` },
+                    propsPayload: serializeProps({}),
+                    ssrPreview: ssrPreviewEnabled,
+                    hydration: ssrPreviewEnabled ? "islands" : "full",
+                    clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
+                    buildVersion,
+                }));
+            }
+        };
+        if (urlPath === CLIENT_ROUTER_BOOTSTRAP_PATH) {
+            kind = "hmr";
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/javascript; charset=utf-8");
+            response.setHeader("cache-control", "no-store");
+            response.end(clientBootstrapScript);
+            return;
+        }
+        if (urlPath === HMR_CLIENT_PATH) {
+            kind = "hmr";
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/javascript; charset=utf-8");
+            response.setHeader("cache-control", "no-store");
+            response.end(HMR_CLIENT_SCRIPT);
+            return;
+        }
+        if (urlPath.startsWith(`${DEV_CLIENT_ENTRY_PREFIX}/`)) {
+            kind = "asset";
+            const assetFilePath = devClientAssets.get(urlPath);
+            if (!assetFilePath) {
+                response.statusCode = 404;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("Not Found");
+                return;
+            }
+            try {
+                const code = await readFile(assetFilePath);
+                response.statusCode = 200;
+                response.setHeader("content-type", CONTENT_TYPES[extname(assetFilePath)] ?? "application/octet-stream");
+                response.setHeader("cache-control", "no-store");
+                response.end(code);
+            }
+            catch {
+                response.statusCode = 404;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("Not Found");
+            }
+            return;
+        }
+        if (urlPath === INSPECTOR_PATH || urlPath === INSPECTOR_API_PATH) {
+            kind = "inspector";
+            const snapshot = inspector.getSnapshot();
+            if (urlPath === INSPECTOR_API_PATH) {
+                response.statusCode = 200;
+                response.setHeader("content-type", "application/json; charset=utf-8");
+                response.end(JSON.stringify(snapshot, null, 2));
+                return;
+            }
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            response.end(renderInspectorHtml(snapshot));
+            return;
+        }
+        if (options.dynamicPageApi) {
+            const apiResult = await handleDynamicPageApiRequest({
+                method: request.method ?? "GET",
+                pathname: urlPath,
+                query: requestUrl.searchParams,
+                headers: request.headers,
+            }, options.dynamicPageApi);
+            if (apiResult) {
+                kind = "api";
+                response.statusCode = apiResult.status;
+                for (const [key, value] of Object.entries(apiResult.headers)) {
+                    response.setHeader(key, value);
+                }
+                response.end(apiResult.body ?? "");
+                return;
+            }
+        }
+        if (urlPath === prefetchPath && request.method === "POST") {
+            kind = "route";
+            const target = getQueryValue(request.url, "path");
+            if (!target) {
+                response.statusCode = 400;
+                response.setHeader("content-type", "application/json; charset=utf-8");
+                response.end(JSON.stringify({ ok: false, error: "Missing path" }));
+                return;
+            }
+            const resolvedTarget = await resolveRouteForRequest(target);
+            if (resolvedTarget.type === "file") {
+                await respondWithRoute(resolvedTarget.match);
+                return;
+            }
+            if (resolvedTarget.type === "redirect") {
+                response.statusCode = 200;
+                response.setHeader("content-type", "application/json; charset=utf-8");
+                response.end(JSON.stringify({ ok: true, redirect: resolvedTarget.location }));
+                return;
+            }
+            if (resolvedTarget.type === "dynamic") {
+                response.statusCode = 200;
+                response.setHeader("content-type", "application/json; charset=utf-8");
+                response.end(JSON.stringify({
+                    ok: true,
+                    dynamic: true,
+                    mode: resolvedTarget.mode,
+                    warnings: resolvedTarget.warnings,
+                }));
+                return;
+            }
+            if (resolvedTarget.type === "notfound") {
+                response.statusCode = 404;
+                response.setHeader("content-type", "application/json; charset=utf-8");
+                response.end(JSON.stringify({ ok: false, error: "Route not found" }));
+                return;
+            }
+            return;
+        }
+        const publicPath = resolveFilePath(resolvedPublicDir, urlPath);
+        if (publicPath) {
+            try {
+                const stats = await stat(publicPath);
+                if (!stats.isFile()) {
+                    throw new Error("Not a file");
+                }
+                const data = await readFile(publicPath);
+                kind = "asset";
+                response.statusCode = 200;
+                response.setHeader("content-type", CONTENT_TYPES[extname(publicPath)] ?? "application/octet-stream");
+                response.end(data);
+            }
+            catch {
+                const resolvedRoute = await resolveRouteForRequest(urlPath);
+                if (await respondWithResolvedRoute(resolvedRoute, urlPath)) {
+                    return;
+                }
+                response.statusCode = 404;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("Not Found");
+            }
+            return;
+        }
+        const resolvedRoute = await resolveRouteForRequest(urlPath);
+        if (await respondWithResolvedRoute(resolvedRoute, urlPath)) {
+            return;
+        }
+        kind = "notfound";
+        response.statusCode = 404;
+        response.setHeader("content-type", "text/plain; charset=utf-8");
+        response.end("Not Found");
+    });
+    const hmr = createHmrServer(server, { path: HMR_WS_PATH });
+    const watchPaths = Array.from(new Set([resolvedRootDir, resolvedRoutesDir, resolvedPublicDir]));
+    const ignoredWatchRoots = [
+        normalizedNodeModulesDir,
+        normalizedGitDir,
+        normalizedInternalDir,
+        normalizedCacheDir,
+        normalizedOutDir,
+    ];
+    const isIgnoredWatchPath = (changedPath) => ignoredWatchRoots.some((ignoredRoot) => isPathWithinRoot(ignoredRoot, changedPath));
+    const watcher = createFileWatcher({
+        paths: watchPaths,
+        onInvalidate: (changedPaths) => {
+            void (async () => {
+                const watchedChangedPaths = changedPaths
+                    .map((path) => normalizeCachePath(path))
+                    .filter((path) => !isIgnoredWatchPath(path));
+                if (watchedChangedPaths.length === 0) {
+                    return;
+                }
+                const { normalizedChangedPaths, hmrRoutes } = await refreshDynamicGraphForChanges(watchedChangedPaths);
+                const hmrRouteList = hmrRoutes.length > 0 ? hmrRoutes : undefined;
+                const cssUpdates = [];
+                const refreshUpdates = [];
+                let needsReload = false;
+                // Prefer React refresh for JS/TS changes; fallback to full reload for unknown changes.
+                for (const changedPath of normalizedChangedPaths) {
+                    if (changedPath.startsWith(normalizedPublicDir) && extname(changedPath) === ".css") {
+                        const url = toPublicUrl(resolvedPublicDir, changedPath);
+                        if (url) {
+                            cssUpdates.push(url);
+                            continue;
+                        }
+                    }
+                    if ((changedPath.startsWith(normalizedRoutesDir) ||
+                        changedPath.startsWith(normalizedRootDir)) &&
+                        isJavaScriptLike(changedPath)) {
+                        refreshUpdates.push(changedPath);
+                        continue;
+                    }
+                    needsReload = true;
+                }
+                if (needsReload) {
+                    logger.warn("HMR fell back to full reload", {
+                        changedPaths: normalizedChangedPaths,
+                    });
+                    hmr.broadcastFullReload(normalizedChangedPaths, hmrRouteList);
+                    return;
+                }
+                if (refreshUpdates.length > 0) {
+                    hmr.broadcastReactRefresh(refreshUpdates, hmrRouteList);
+                    return;
+                }
+                if (cssUpdates.length > 0) {
+                    hmr.broadcastCssUpdate(cssUpdates);
+                }
+            })().catch((error) => {
+                const { message, stack } = toErrorInfo(error);
+                logger.error("Watcher invalidation failed", {
+                    changedPaths,
+                    message,
+                });
+                if (stack) {
+                    logger.error("Watcher invalidation stack", { stack });
+                }
+                hmr.broadcastFullReload(changedPaths);
+            });
+        },
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, host, () => resolve());
+        });
+    }
+    catch (error) {
+        const { message, stack } = toErrorInfo(error);
+        logger.fatal("Dev server failed to start", {
+            host,
+            port,
+            rootDir: resolvedRootDir,
+            message,
+        });
+        if (stack) {
+            logger.error("Dev server startup stack", { stack });
+        }
+        throw error;
+    }
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Dev server did not return a TCP address.");
+    }
+    // Ensure we capture the real port when port=0 for ephemeral assignments.
+    const url = `http://${address.address}:${address.port}`;
+    return {
+        host: address.address,
+        port: address.port,
+        url,
+        hmr,
+        invalidate: (paths) => {
+            void refreshDynamicGraphForChanges(paths).catch((error) => {
+                const { message, stack } = toErrorInfo(error);
+                logger.error("Manual invalidation failed", { paths, message });
+                if (stack) {
+                    logger.error("Manual invalidation stack", { stack });
+                }
+            });
+        },
+        close: () => new Promise((resolve, reject) => {
+            watcher.close();
+            hmr.close();
+            inflightRouteRenders.clear();
+            for (const routeRenderVersions of routeRenderDirectories.values()) {
+                for (const renderDir of routeRenderVersions.values()) {
+                    void rm(renderDir, { recursive: true, force: true }).catch(() => { });
+                }
+            }
+            routeRenderDirectories.clear();
+            server.close((error) => {
+                if (error) {
+                    const { message, stack } = toErrorInfo(error);
+                    logger.error("Dev server close failed", { message });
+                    if (stack) {
+                        logger.error("Dev server close stack", { stack });
+                    }
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+    };
+};