@tyndall/dev 0.0.1 → 0.0.2

package/README.md

@@ -12,6 +12,9 @@ Development server package with watcher integration, route rendering, and HMR tr
 - Emit adapter-driven client runtime scripts for route hydration in dev mode
 - Serve route runtime chunk assets (`/_hyper/dev-client/*`) so client route modules can load on demand after navigation
 - Preserve hydration during HMR fallback by applying route payload updates through a mounted-root-safe rerender bridge
+- Resolve root special files (`_app`, `_document`, `_404`, `_error`, `init.server`) during route graph refresh
+- Collect route data payloads and inject `__HYPER_ROUTE_DATA__` into dev HTML + CSR payloads
+- Emit redirect payloads for client-side navigation requests
 - Filter broad `routesDir` scans so internal artifacts (`.hyper`, cache, `node_modules`, `outDir`, `.git`) never become file routes
 - Stabilize Bun dev runtime bundling by aliasing critical React/runtime dependencies to cache-local concrete files (not workspace symlink paths)
 - Track nested layout files as route dependencies for dev snapshotting and HMR invalidation

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAaL,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAG3B,KAAK,iBAAiB,EAGvB,MAAM,eAAe,CAAC;AAWvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAU9C,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE7F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACxC;AA4WD,eAAO,MAAM,cAAc,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,SAAS,CAyyCtF,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAyBL,KAAK,sBAAsB,EAG3B,KAAK,sBAAsB,EAG3B,KAAK,iBAAiB,EAIvB,MAAM,eAAe,CAAC;AAYvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAU9C,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE7F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACxC;AAspBD,eAAO,MAAM,cAAc,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,SAAS,CA8tDtF,CAAC"}

package/dist/index.js

@@ -3,8 +3,8 @@ import { copyFile, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/prom
 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 { CLIENT_ROUTER_BOOTSTRAP_PATH, ROUTE_DATA_ERROR_KEY, ROUTE_DATA_INIT_KEY, ROUTE_DATA_SCRIPT_ID, SPECIAL_ROUTE_IDS, collectRouteLayouts, createRouteGraph, handleDynamicPageApiRequest, loadConfig, resolveLayoutRouteId, renderClientRouterBootstrap, resolvePageModule, resolveRouteWithPolicyFallback, resolveUIAdapter, routeDataKeyForLayout, routeDataKeyForPage, runBeforeBundleHooks, runGetRouteData, runGetServerProps, runInitServer, serializeProps, } from "@tyndall/core";
+import { createLogger, buildModuleGraphSnapshot, 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";
@@ -116,6 +116,192 @@ const renderHeadDescriptor = (head) => {
     }
     return parts.join("");
 };
+const renderStyleLinks = (styles) => styles.map((href) => `<link rel=\"stylesheet\" href=\"${escapeHtml(href)}\">`).join("");
+const normalizeRedirect = (redirect) => {
+    if (!redirect) {
+        return null;
+    }
+    if (typeof redirect === "string") {
+        return { destination: redirect };
+    }
+    return {
+        destination: redirect.destination,
+        status: redirect.status,
+        replace: redirect.replace,
+    };
+};
+const normalizeError = (error) => {
+    if (!error) {
+        return null;
+    }
+    if (typeof error === "string") {
+        return { message: error };
+    }
+    return {
+        status: error.status,
+        message: error.message,
+    };
+};
+const resolveRouteDataHook = (module) => {
+    if (module && typeof module === "object") {
+        const record = module;
+        if (typeof record.getRouteData === "function") {
+            return record.getRouteData;
+        }
+    }
+    return undefined;
+};
+const resolveInitServerHook = (module) => {
+    if (module && typeof module === "object") {
+        const record = module;
+        if (typeof record.initServer === "function") {
+            return record.initServer;
+        }
+        if (typeof record.default === "function") {
+            return record.default;
+        }
+    }
+    return undefined;
+};
+const collectRouteDataForRoute = async (input) => {
+    const dataMap = {};
+    const headers = {};
+    let status;
+    let redirect;
+    let error;
+    let initData;
+    let parentData;
+    if (input.initServerHook) {
+        const initResult = await runInitServer(input.initServerHook, {
+            routeId: input.routeId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+        });
+        if (initResult.data !== undefined) {
+            initData = initResult.data;
+            dataMap[ROUTE_DATA_INIT_KEY] = initResult.data;
+        }
+        if (initResult.headers) {
+            Object.assign(headers, initResult.headers);
+        }
+        if (initResult.status !== undefined) {
+            status = initResult.status;
+        }
+        if (initResult.redirect) {
+            redirect = initResult.redirect;
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+        if (initResult.error) {
+            error = initResult.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+    }
+    const layoutFiles = input.layoutFiles ?? [];
+    for (const layoutFile of layoutFiles) {
+        const layoutModule = await input.loadLayoutModule(layoutFile);
+        const hook = resolveRouteDataHook(layoutModule);
+        if (!hook) {
+            continue;
+        }
+        const layoutId = resolveLayoutRouteId(layoutFile, input.routesDir);
+        const result = await runGetRouteData(hook, {
+            routeId: layoutId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+            init: initData,
+            routeData: dataMap,
+            parentData,
+        });
+        if (result.data !== undefined) {
+            dataMap[routeDataKeyForLayout(layoutId)] = result.data;
+            parentData = result.data;
+        }
+        if (result.headers) {
+            Object.assign(headers, result.headers);
+        }
+        if (result.status !== undefined) {
+            status = result.status;
+        }
+        if (result.redirect) {
+            redirect = result.redirect;
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+        if (result.error) {
+            error = result.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+            return { data: dataMap, initData, headers, status, redirect, error };
+        }
+    }
+    if (input.pageModule?.getRouteData) {
+        const result = await runGetRouteData(input.pageModule.getRouteData, {
+            routeId: input.routeId,
+            params: input.params,
+            request: input.request,
+            response: input.response,
+            init: initData,
+            routeData: dataMap,
+            parentData,
+        });
+        if (result.data !== undefined) {
+            dataMap[routeDataKeyForPage(input.routeId)] = result.data;
+        }
+        if (result.headers) {
+            Object.assign(headers, result.headers);
+        }
+        if (result.status !== undefined) {
+            status = result.status;
+        }
+        if (result.redirect) {
+            redirect = result.redirect;
+        }
+        if (result.error) {
+            error = result.error;
+            const normalizedError = normalizeError(error);
+            if (normalizedError) {
+                dataMap[ROUTE_DATA_ERROR_KEY] = normalizedError;
+            }
+        }
+    }
+    return { data: dataMap, initData, headers, status, redirect, error };
+};
+const renderStaticRedirectDocument = (destination) => {
+    const safe = escapeHtml(destination);
+    return [
+        "<!doctype html>",
+        "<html>",
+        "<head>",
+        `<meta http-equiv=\"refresh\" content=\"0;url=${safe}\">`,
+        `<script>window.location.replace(${JSON.stringify(destination)});</script>`,
+        "</head>",
+        "<body>",
+        `<a href=\"${safe}\">Redirecting...</a>`,
+        "</body>",
+        "</html>",
+    ].join("");
+};
+const renderStaticErrorDocument = (message) => {
+    const safe = escapeHtml(message);
+    return [
+        "<!doctype html>",
+        "<html>",
+        "<head>",
+        "<title>Route data error</title>",
+        "</head>",
+        "<body>",
+        `<main>${safe}</main>`,
+        "</body>",
+        "</html>",
+    ].join("");
+};
 const renderDevDocument = (input) => {
     const htmlAttrs = input.ssrPreview ? ' data-hyper-ssr="true"' : "";
     const buildVersionMeta = input.buildVersion
@@ -124,19 +310,63 @@ const renderDevDocument = (input) => {
     const buildVersionAttr = input.buildVersion
         ? ` data-hyper-build-version=\"${escapeHtml(input.buildVersion)}\"`
         : "";
+    const styles = input.styles ?? [];
+    const stylesHtml = renderStyleLinks(styles);
     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}\"`;
+    const scripts = [
+        input.clientBootstrapScriptPath,
+        ...(input.clientRuntimeScriptPath ? [input.clientRuntimeScriptPath] : []),
+        HMR_CLIENT_PATH,
+    ];
+    const documentCtx = {
+        html: input.appHtml,
+        head: input.head,
+        propsPayload: input.propsPayload,
+        routeDataPayload: input.routeDataPayload,
+        routeId: input.routeId,
+        hydration: input.hydration,
+        scripts,
+        legacyScripts: [],
+        styles,
+        scriptType: "module",
+        buildVersion: input.buildVersion ?? "",
+    };
+    if (input.renderDocument) {
+        try {
+            const custom = input.renderDocument(documentCtx);
+            if (typeof custom === "string") {
+                return custom;
+            }
+        }
+        catch {
+            // Fall back to default document if custom render fails.
+        }
+    }
+    if (input.renderDocumentFragments) {
+        try {
+            const fragments = input.renderDocumentFragments(documentCtx);
+            if (fragments && typeof fragments.prefix === "string" && typeof fragments.suffix === "string") {
+                return `${fragments.prefix}${input.appHtml}${fragments.suffix}`;
+            }
+        }
+        catch {
+            // Fall back to default document if fragments fail.
+        }
+    }
     return [
         "<!doctype html>",
         `<html${htmlAttrs}${buildVersionAttr}>`,
         "<head>",
         renderHeadDescriptor(input.head),
         buildVersionMeta,
+        stylesHtml,
         "</head>",
         "<body>",
         `<div id=\"app\"${appAttrs}>${input.appHtml}</div>`,
         `<script id=\"__HYPER_PROPS__\" type=\"application/json\">${input.propsPayload}</script>`,
+        `<script id=\"${ROUTE_DATA_SCRIPT_ID}\" type=\"application/json\">${input.routeDataPayload}</script>`,
         `<script>window.__HYPER_ROUTE_ID__ = ${JSON.stringify(input.routeId)};</script>`,
         `<script type=\"module\" src=\"${input.clientBootstrapScriptPath}\"></script>`,
         ...(input.clientRuntimeScriptPath
@@ -152,6 +382,7 @@ const buildRoutePayload = (rendered) => ({
     routeId: rendered.routeId,
     appHtml: rendered.appHtml,
     propsPayload: rendered.propsPayload,
+    routeDataPayload: rendered.routeDataPayload,
     clientRuntimeScriptPath: rendered.clientRuntimeScriptPath,
     head: rendered.head,
     hydration: rendered.hydration,
@@ -217,6 +448,7 @@ const isJavaScriptOutputAsset = (filePath) => {
     const ext = extname(filePath);
     return ext === ".js" || ext === ".mjs";
 };
+const isStyleOutputAsset = (filePath) => extname(filePath) === ".css";
 const isRuntimeOutputAsset = (filePath) => {
     const ext = extname(filePath);
     return ext === ".js" || ext === ".mjs" || ext === ".css";
@@ -280,6 +512,7 @@ export const startDevServer = async (options = {}) => {
     const port = options.port ?? 3000;
     const rootDir = options.rootDir ?? process.cwd();
     const config = await loadConfig(rootDir);
+    const hyperPlugins = config.plugins;
     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;
@@ -293,6 +526,7 @@ export const startDevServer = async (options = {}) => {
         navigationMode: ssrClientRoutingEnabled ? "client" : config.routing.navigation,
         clientRenderMode: config.routing.clientRender,
         linkInterceptionMode: ssrClientRoutingEnabled ? "all" : "marked",
+        scrollRestoration: config.routing.scrollRestoration,
     });
     const routesDir = options.routesDir ?? config.routesDir;
     const publicDir = options.publicDir ?? config.publicDir;
@@ -318,6 +552,7 @@ export const startDevServer = async (options = {}) => {
     const isIgnoredRouteGraphPath = (targetPath) => ignoredRouteGraphRoots.some((ignoredRoot) => isPathWithinRoot(ignoredRoot, targetPath));
     const filterRouteGraph = (graph) => ({
         routes: graph.routes.filter((route) => !isIgnoredRouteGraphPath(route.filePath)),
+        specialFiles: graph.specialFiles,
     });
     let routeGraph = filterRouteGraph(await loadRouteGraph(resolvedRoutesDir, config.routing.routeMeta, config.routing.nestedLayouts));
     const inspector = createDevInspector();
@@ -344,12 +579,34 @@ export const startDevServer = async (options = {}) => {
         }
         return { byFile };
     };
+    const resolveSpecialRouteRecords = (graph, routesDir) => {
+        const records = { notFound: null, error: null };
+        if (graph.specialFiles?.notFound) {
+            const resolution = collectRouteLayouts(graph.specialFiles.notFound, routesDir);
+            records.notFound = {
+                id: SPECIAL_ROUTE_IDS.notFound,
+                filePath: graph.specialFiles.notFound,
+                layoutFiles: resolution.layoutFiles,
+            };
+        }
+        if (graph.specialFiles?.error) {
+            const resolution = collectRouteLayouts(graph.specialFiles.error, routesDir);
+            records.error = {
+                id: SPECIAL_ROUTE_IDS.error,
+                filePath: graph.specialFiles.error,
+                layoutFiles: resolution.layoutFiles,
+            };
+        }
+        return records;
+    };
     let routeIndex = buildRouteIndex(routeGraph);
     let layoutIndex = buildLayoutIndex(routeGraph);
+    let specialRouteRecords = resolveSpecialRouteRecords(routeGraph, resolvedRoutesDir);
     const setRouteGraph = (graph) => {
         routeGraph = graph;
         routeIndex = buildRouteIndex(graph);
         layoutIndex = buildLayoutIndex(graph);
+        specialRouteRecords = resolveSpecialRouteRecords(graph, resolvedRoutesDir);
     };
     const uiAdapter = typeof config.ui.adapter === "string"
         ? config.ui.adapter
@@ -506,11 +763,19 @@ export const startDevServer = async (options = {}) => {
         const propsPath = await resolveCoreShimModulePath(entryDir, "props");
         const renderPolicyPath = await resolveCoreShimModulePath(entryDir, "render-policy");
         const resolverFallbackPath = await resolveCoreShimModulePath(entryDir, "resolver-fallback");
+        const routeDataPath = await resolveCoreShimModulePath(entryDir, "route-data");
         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)};`,
+            `export {`,
+            `  ROUTE_DATA_SCRIPT_ID,`,
+            `  ROUTE_DATA_INIT_KEY,`,
+            `  ROUTE_DATA_ERROR_KEY,`,
+            `  routeDataKeyForPage,`,
+            `  routeDataKeyForLayout,`,
+            `} from ${JSON.stringify(routeDataPath)};`,
         ].join("\n");
         return hyperCoreBrowserShimSource;
     };
@@ -564,6 +829,7 @@ export const startDevServer = async (options = {}) => {
         routeGraph,
         rootDir: resolvedRootDir,
         routeRoot: loaded.routeRoot,
+        appModule: routeGraph.specialFiles?.app,
         routeRender: pageRender,
         routeHead: pageHead,
     }, options.adapterRegistry);
@@ -579,6 +845,35 @@ export const startDevServer = async (options = {}) => {
         }
         return normalizedModules;
     };
+    const SERVER_ONLY_MODULE_PATTERN = /\.server\.[cm]?[jt]sx?$/i;
+    const collectServerOnlyModules = (modules) => {
+        const offenders = [];
+        for (const modulePath of modules) {
+            if (SERVER_ONLY_MODULE_PATTERN.test(modulePath)) {
+                offenders.push(modulePath);
+            }
+        }
+        return offenders;
+    };
+    const assertNoServerOnlyClientImports = (routeId, modules) => {
+        const offenders = collectServerOnlyModules(modules);
+        const appModule = routeGraph.specialFiles?.app;
+        const appOffenders = appModule
+            ? collectServerOnlyModules(buildModuleGraphSnapshot([{ id: "__hyper_app__", filePath: appModule }])
+                .routeToModules.__hyper_app__ ?? [])
+            : [];
+        if (offenders.length === 0 && appOffenders.length === 0) {
+            return;
+        }
+        const details = [];
+        if (offenders.length > 0) {
+            details.push(`route "${routeId}": ${offenders.join(", ")}`);
+        }
+        if (appOffenders.length > 0) {
+            details.push(`app: ${appOffenders.join(", ")}`);
+        }
+        throw new Error(`Server-only modules (.server.*) cannot be imported into client bundles. Found ${details.join(" | ")}.`);
+    };
     const shouldCopyRouteSnapshotModule = (modulePath) => {
         if (!isPathWithinRoot(resolvedRootDir, modulePath)) {
             return false;
@@ -643,31 +938,41 @@ export const startDevServer = async (options = {}) => {
         if (typeof adapter.createClientEntry !== "function") {
             return undefined;
         }
+        // Guard: client runtime bundling must not include server-only modules.
+        assertNoServerOnlyClientImports(route.id, resolveRouteModulesForRender(route));
         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 appModule = routeGraph.specialFiles?.app
+            ? toImportSpecifier(routeRoot, routeGraph.specialFiles.app)
+            : undefined;
         const entrySource = adapter.createClientEntry({
             routeId: route.id,
             routeGraph,
             rootDir: resolvedRootDir,
             entryDir: routeRoot,
             routeRoot,
+            entryLayoutFiles: route.layoutFiles,
             uiOptions: {
                 ...config.ui.options,
                 pageModule,
+                appModule,
                 navigationMode: config.routing.navigation,
                 clientRenderMode: config.routing.clientRender,
+                scrollRestoration: config.routing.scrollRestoration,
                 clientRouteModules: routeModuleMap,
                 nestedLayouts: config.routing.nestedLayouts,
             },
             adapterOptions: {
                 ...config.ui.options,
                 pageModule,
+                appModule,
                 navigationMode: config.routing.navigation,
                 clientRenderMode: config.routing.clientRender,
+                scrollRestoration: config.routing.scrollRestoration,
                 clientRouteModules: routeModuleMap,
                 nestedLayouts: config.routing.nestedLayouts,
             },
@@ -689,6 +994,23 @@ export const startDevServer = async (options = {}) => {
         const runtimeDependencyAliasPattern = runtimeDependencyAliasSpecifiers.length > 0
             ? new RegExp(`^(?:${runtimeDependencyAliasSpecifiers.map((specifier) => escapeRegExp(specifier)).join("|")})$`)
             : null;
+        const hookPlugins = [];
+        if (hyperPlugins.length > 0) {
+            await runBeforeBundleHooks(hyperPlugins, {
+                phase: "dev",
+                entryId: route.id,
+                entryPath: entryFilePath,
+                target: "browser",
+                format: "esm",
+                syntaxTarget: "modern",
+                bundler: "bun",
+                bundleType: "client",
+                bundlerPlugins: hookPlugins,
+                addBundlerPlugin: (plugin) => {
+                    hookPlugins.push(plugin);
+                },
+            });
+        }
         const plugins = [
             {
                 name: "@tyndall/core-browser-shim",
@@ -721,6 +1043,7 @@ export const startDevServer = async (options = {}) => {
                     },
                 ]
                 : []),
+            ...hookPlugins,
         ];
         let buildResult;
         for (let attempt = 0; attempt <= DEV_RUNTIME_BUILD_RETRY_COUNT; attempt += 1) {
@@ -772,6 +1095,7 @@ export const startDevServer = async (options = {}) => {
         }
         const assetPrefix = `${getRouteAssetPrefix(route.id)}${loaded.version}/`;
         let scriptPath;
+        const stylePaths = [];
         for (const outputPath of outputAssets) {
             const relativeOutputPath = normalizePath(relative(outDir, outputPath));
             if (relativeOutputPath.length === 0 ||
@@ -781,6 +1105,9 @@ export const startDevServer = async (options = {}) => {
             }
             const publicPath = `${assetPrefix}${relativeOutputPath}`;
             devClientAssets.set(publicPath, outputPath);
+            if (isStyleOutputAsset(outputPath)) {
+                stylePaths.push(publicPath);
+            }
             if (!scriptPath &&
                 isJavaScriptOutputAsset(outputPath) &&
                 (relativeOutputPath === "__hyper_client_entry.js" ||
@@ -800,7 +1127,159 @@ export const startDevServer = async (options = {}) => {
         }
         trackRouteAssetVersion(route.id, loaded.version);
         pruneStaleRouteAssetVersions(route.id);
-        return scriptPath;
+        return scriptPath ? { scriptPath, stylePaths } : undefined;
+    };
+    const loadInitServerModule = async () => {
+        const initServerPath = routeGraph.specialFiles?.initServer;
+        if (!initServerPath) {
+            return null;
+        }
+        try {
+            return await import(`${pathToFileURL(initServerPath).href}?dev=${Date.now()}`);
+        }
+        catch {
+            return null;
+        }
+    };
+    const loadDocumentModule = async () => {
+        const documentPath = routeGraph.specialFiles?.document;
+        if (!documentPath) {
+            return null;
+        }
+        try {
+            return await import(`${pathToFileURL(documentPath).href}?dev=${Date.now()}`);
+        }
+        catch {
+            return null;
+        }
+    };
+    const resolveDocumentRenderers = async () => {
+        const module = await loadDocumentModule();
+        if (!module || typeof module !== "object") {
+            return { renderDocument: undefined, renderDocumentFragments: undefined };
+        }
+        const record = module;
+        const renderDocument = typeof record.renderDocument === "function"
+            ? record.renderDocument
+            : typeof record.default === "function"
+                ? record.default
+                : undefined;
+        const renderDocumentFragments = typeof record.renderDocumentFragments === "function"
+            ? record.renderDocumentFragments
+            : undefined;
+        return { renderDocument, renderDocumentFragments };
+    };
+    const renderSpecialRoute = async (input) => {
+        const specialRoute = {
+            id: input.record.id,
+            filePath: input.record.filePath,
+            segments: [],
+            layoutFiles: input.record.layoutFiles,
+        };
+        const loaded = await loadRouteModule(specialRoute);
+        const page = resolvePageModule(loaded.module);
+        const adapter = resolveAdapterForRoute(specialRoute, 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.`);
+        }
+        const loadLayoutModule = async (layoutFile) => {
+            if (loaded.routeRoot) {
+                const relativePath = relative(resolvedRootDir, layoutFile);
+                if (relativePath && !relativePath.startsWith(`..${sep}`) && relativePath !== "..") {
+                    const snapshotPath = join(loaded.routeRoot, relativePath);
+                    try {
+                        return await import(pathToFileURL(snapshotPath).href);
+                    }
+                    catch {
+                        // Fall back to direct import.
+                    }
+                }
+            }
+            return await import(`${pathToFileURL(layoutFile).href}?dev=${Date.now()}`);
+        };
+        const initServerModule = await loadInitServerModule();
+        const initServerHook = resolveInitServerHook(initServerModule);
+        const routeDataResult = await collectRouteDataForRoute({
+            routeId: specialRoute.id,
+            routesDir: resolvedRoutesDir,
+            params: undefined,
+            layoutFiles: specialRoute.layoutFiles,
+            pageModule: page,
+            initServerHook,
+            request: input.request,
+            response: input.response,
+            loadLayoutModule,
+        });
+        const mergedRouteData = { ...routeDataResult.data, ...(input.extraRouteData ?? {}) };
+        const serverProps = page.getServerProps
+            ? await runGetServerProps(page.getServerProps, {
+                routeId: specialRoute.id,
+                params: undefined,
+                request: input.request,
+                response: input.response,
+                init: routeDataResult.initData,
+                routeData: mergedRouteData,
+            })
+            : null;
+        const props = {
+            ...(serverProps?.props ?? {}),
+            ...(input.extraProps ?? {}),
+        };
+        const rendered = await adapter.renderToHtml({
+            routeId: specialRoute.id,
+            params: undefined,
+            props,
+            routeData: mergedRouteData,
+        });
+        const payload = adapter.serializeProps?.(props) ?? serializeProps(props);
+        const routeDataPayload = adapter.serializeProps?.(mergedRouteData) ?? serializeProps(mergedRouteData);
+        let clientRuntimeScriptPath;
+        let clientRuntimeStyles = [];
+        try {
+            const runtimeAssets = await buildClientRuntimeScript(specialRoute, loaded, adapter);
+            clientRuntimeScriptPath = runtimeAssets?.scriptPath;
+            clientRuntimeStyles = runtimeAssets?.stylePaths ?? [];
+        }
+        catch (error) {
+            const info = toErrorInfo(error);
+            logger.warn("Dev client runtime build failed for special route", {
+                routeId: specialRoute.id,
+                message: info.message,
+            });
+        }
+        const hydration = ssrPreviewEnabled ? "islands" : "full";
+        const documentRenderers = await resolveDocumentRenderers();
+        const html = renderDevDocument({
+            routeId: specialRoute.id,
+            appHtml: rendered.html,
+            head: rendered.head ?? {},
+            propsPayload: payload,
+            routeDataPayload,
+            ssrPreview: ssrPreviewEnabled,
+            hydration,
+            clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
+            clientRuntimeScriptPath,
+            styles: clientRuntimeStyles,
+            buildVersion,
+            ...documentRenderers,
+        });
+        return {
+            html,
+            routeId: specialRoute.id,
+            appHtml: rendered.html,
+            head: rendered.head ?? {},
+            propsPayload: payload,
+            routeDataPayload,
+            clientRuntimeScriptPath,
+            styles: clientRuntimeStyles,
+            hydration,
+            status: input.statusOverride ?? rendered.status ?? serverProps?.status ?? routeDataResult.status ?? 200,
+            headers: {
+                ...routeDataResult.headers,
+                ...(serverProps?.headers ?? {}),
+                ...(rendered.headers ?? {}),
+            },
+        };
     };
     const renderRoute = async (match, request, response) => {
         const loaded = await loadRouteModule(match.route);
@@ -809,6 +1288,99 @@ export const startDevServer = async (options = {}) => {
         if (typeof adapter.renderToHtml !== "function") {
             throw new Error(`UI adapter "${adapter.name}" does not support renderToHtml.`);
         }
+        const loadLayoutModule = async (layoutFile) => {
+            if (loaded.routeRoot) {
+                const relativePath = relative(resolvedRootDir, layoutFile);
+                if (relativePath && !relativePath.startsWith(`..${sep}`) && relativePath !== "..") {
+                    const snapshotPath = join(loaded.routeRoot, relativePath);
+                    try {
+                        return await import(pathToFileURL(snapshotPath).href);
+                    }
+                    catch {
+                        // Fall back to direct import.
+                    }
+                }
+            }
+            return await import(`${pathToFileURL(layoutFile).href}?dev=${Date.now()}`);
+        };
+        const initServerModule = await loadInitServerModule();
+        const initServerHook = resolveInitServerHook(initServerModule);
+        const routeDataResult = await collectRouteDataForRoute({
+            routeId: match.route.id,
+            routesDir: resolvedRoutesDir,
+            params: match.params,
+            layoutFiles: match.route.layoutFiles,
+            pageModule: page,
+            initServerHook,
+            request,
+            response,
+            loadLayoutModule,
+        });
+        const redirect = normalizeRedirect(routeDataResult.redirect);
+        if (redirect) {
+            return {
+                html: renderStaticRedirectDocument(redirect.destination),
+                routeId: match.route.id,
+                appHtml: "",
+                head: { title: `Redirect ${match.route.id}` },
+                propsPayload: serializeProps({}),
+                routeDataPayload: serializeProps(routeDataResult.data),
+                hydration: ssrPreviewEnabled ? "islands" : "full",
+                status: redirect.status ?? routeDataResult.status ?? 302,
+                headers: {
+                    ...routeDataResult.headers,
+                    location: redirect.destination,
+                },
+                redirect,
+            };
+        }
+        if (routeDataResult.error) {
+            const normalizedError = normalizeError(routeDataResult.error);
+            if (specialRouteRecords.error) {
+                return await renderSpecialRoute({
+                    record: specialRouteRecords.error,
+                    request,
+                    response,
+                    extraProps: {
+                        error: normalizedError,
+                        routeId: match.route.id,
+                    },
+                    extraRouteData: normalizedError
+                        ? {
+                            [ROUTE_DATA_ERROR_KEY]: normalizedError,
+                        }
+                        : undefined,
+                });
+            }
+            const message = normalizedError?.message ?? "Route data error";
+            const appErrorHtml = `<main><h1>Route Data Error</h1><pre>${escapeHtml(message)}</pre></main>`;
+            const documentRenderers = await resolveDocumentRenderers();
+            const html = renderDevDocument({
+                routeId: match.route.id,
+                appHtml: appErrorHtml,
+                head: { title: `Dev Error ${match.route.id}` },
+                propsPayload: serializeProps({}),
+                routeDataPayload: serializeProps(routeDataResult.data),
+                ssrPreview: ssrPreviewEnabled,
+                hydration: ssrPreviewEnabled ? "islands" : "full",
+                clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
+                buildVersion,
+                ...documentRenderers,
+            });
+            return {
+                html,
+                routeId: match.route.id,
+                appHtml: appErrorHtml,
+                head: { title: `Dev Error ${match.route.id}` },
+                propsPayload: serializeProps({}),
+                routeDataPayload: serializeProps(routeDataResult.data),
+                hydration: ssrPreviewEnabled ? "islands" : "full",
+                status: normalizedError?.status ?? routeDataResult.status ?? 500,
+                headers: {
+                    ...routeDataResult.headers,
+                },
+            };
+        }
         // Run server props in dev whenever the route exports it so page contracts stay consistent.
         const serverProps = page.getServerProps
             ? await runGetServerProps(page.getServerProps, {
@@ -816,6 +1388,8 @@ export const startDevServer = async (options = {}) => {
                 params: match.params,
                 request,
                 response,
+                init: routeDataResult.initData,
+                routeData: routeDataResult.data,
             })
             : null;
         const props = serverProps?.props ?? {};
@@ -823,11 +1397,16 @@ export const startDevServer = async (options = {}) => {
             routeId: match.route.id,
             params: match.params,
             props,
+            routeData: routeDataResult.data,
         });
         const payload = adapter.serializeProps?.(props) ?? serializeProps(props);
+        const routeDataPayload = adapter.serializeProps?.(routeDataResult.data) ?? serializeProps(routeDataResult.data);
         let clientRuntimeScriptPath;
+        let clientRuntimeStyles = [];
         try {
-            clientRuntimeScriptPath = await buildClientRuntimeScript(match.route, loaded, adapter);
+            const runtimeAssets = await buildClientRuntimeScript(match.route, loaded, adapter);
+            clientRuntimeScriptPath = runtimeAssets?.scriptPath;
+            clientRuntimeStyles = runtimeAssets?.stylePaths ?? [];
         }
         catch (error) {
             const info = toErrorInfo(error);
@@ -837,16 +1416,20 @@ export const startDevServer = async (options = {}) => {
             });
         }
         const hydration = ssrPreviewEnabled ? "islands" : "full";
+        const documentRenderers = await resolveDocumentRenderers();
         const html = renderDevDocument({
             routeId: match.route.id,
             appHtml: rendered.html,
             head: rendered.head ?? {},
             propsPayload: payload,
+            routeDataPayload,
             ssrPreview: ssrPreviewEnabled,
             hydration,
             clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
             clientRuntimeScriptPath,
+            styles: clientRuntimeStyles,
             buildVersion,
+            ...documentRenderers,
         });
         return {
             html,
@@ -854,10 +1437,13 @@ export const startDevServer = async (options = {}) => {
             appHtml: rendered.html,
             head: rendered.head ?? {},
             propsPayload: payload,
+            routeDataPayload,
             clientRuntimeScriptPath,
+            styles: clientRuntimeStyles,
             hydration,
-            status: rendered.status ?? serverProps?.status ?? 200,
+            status: rendered.status ?? serverProps?.status ?? routeDataResult.status ?? 200,
             headers: {
+                ...routeDataResult.headers,
                 ...(serverProps?.headers ?? {}),
                 ...(rendered.headers ?? {}),
             },
@@ -1050,18 +1636,48 @@ export const startDevServer = async (options = {}) => {
                 }
                 response.statusCode = 200;
                 response.setHeader("content-type", "text/html; charset=utf-8");
+                const documentRenderers = await resolveDocumentRenderers();
                 response.end(renderDevDocument({
                     routeId: pathname,
                     appHtml: `<main data-hyper-dynamic=\"true\">Dynamic Route: ${escapeHtml(pathname)}</main>`,
                     head: { title: `Dynamic ${pathname}` },
                     propsPayload: serializeProps({}),
+                    routeDataPayload: serializeProps({}),
                     ssrPreview: ssrPreviewEnabled,
                     hydration: ssrPreviewEnabled ? "islands" : "full",
                     clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
                     buildVersion,
+                    ...documentRenderers,
                 }));
                 return true;
             }
+            if (resolved.type === "notfound") {
+                if (!specialRouteRecords.notFound) {
+                    return false;
+                }
+                kind = "route";
+                routeId = SPECIAL_ROUTE_IDS.notFound;
+                const navigationRequest = isCsrNavigationRequest(request);
+                const rendered = await renderSpecialRoute({
+                    record: specialRouteRecords.notFound,
+                    request,
+                    response,
+                    statusOverride: 404,
+                });
+                response.statusCode = rendered.status;
+                for (const [header, value] of Object.entries(rendered.headers)) {
+                    response.setHeader(header, value);
+                }
+                if (navigationRequest) {
+                    response.setHeader("content-type", "application/json; charset=utf-8");
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.end(JSON.stringify(buildRoutePayload(rendered)));
+                    return true;
+                }
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                response.end(rendered.html);
+                return true;
+            }
             return false;
         };
         const respondWithRoute = async (match) => {
@@ -1107,7 +1723,29 @@ export const startDevServer = async (options = {}) => {
                 for (const [header, value] of Object.entries(rendered.headers)) {
                     response.setHeader(header, value);
                 }
-                routeCache.set(cacheKey, { ...rendered, updatedAt: Date.now() });
+                if (!rendered.redirect) {
+                    routeCache.set(cacheKey, { ...rendered, updatedAt: Date.now() });
+                }
+                if (rendered.redirect) {
+                    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({
+                            kind: "hyper-route-redirect",
+                            destination: rendered.redirect.destination,
+                            status: rendered.redirect.status ?? rendered.status ?? 302,
+                            replace: rendered.redirect.replace ?? false,
+                        }));
+                        return;
+                    }
+                    response.statusCode = rendered.redirect.status ?? rendered.status ?? 302;
+                    response.setHeader("location", rendered.redirect.destination);
+                    response.setHeader("x-hyper-route-cache", "miss");
+                    response.setHeader("content-type", "text/html; charset=utf-8");
+                    response.end(rendered.html);
+                    return;
+                }
                 if (navigationRequest) {
                     response.setHeader("content-type", "application/json; charset=utf-8");
                     response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
@@ -1135,15 +1773,18 @@ export const startDevServer = async (options = {}) => {
                 hmr.broadcastError(message, stack);
                 response.statusCode = 500;
                 response.setHeader("x-hyper-route-cache", "miss");
+                const documentRenderers = await resolveDocumentRenderers();
                 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({}),
+                    routeDataPayload: serializeProps({}),
                     ssrPreview: ssrPreviewEnabled,
                     hydration: ssrPreviewEnabled ? "islands" : "full",
                     clientBootstrapScriptPath: CLIENT_ROUTER_BOOTSTRAP_PATH,
                     buildVersion,
+                    ...documentRenderers,
                 }));
             }
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyndall/dev",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -21,9 +21,9 @@
     "build": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@tyndall/core": "workspace:*",
-    "@tyndall/dynamic-graph": "workspace:*",
-    "@tyndall/shared": "workspace:*",
+    "@tyndall/core": "^0.0.2",
+    "@tyndall/dynamic-graph": "^0.0.2",
+    "@tyndall/shared": "^0.0.2",
     "ws": "^8.18.0"
   }
 }