evolit 0.2.0 → 0.3.0

package/README.md

@@ -46,6 +46,26 @@ Generated applications declare `"@/*": ["./*"]` in `jsconfig.json`, so editors a
 use the same convention. An explicit `@/*` mapping in `jsconfig.json` or `tsconfig.json` takes
 priority when an application needs a different source root.
 
+### Interpolated dynamic imports
+
+Relative dynamic imports may use a template literal when every possible module can be discovered
+from the literal path at build time:
+
+```tsx
+const module = await import(`./templates/${locale}/${name}.tsx`);
+```
+
+Evolit treats each interpolation as one wildcard that matches a single path segment. The example
+above discovers `./templates/*/*.tsx`, compiles every matching module, and emits a finite runtime
+dispatcher whose cases preserve the original source specifiers. Interpolations never cross a `/`,
+and there is no framework-imposed candidate limit.
+
+The template must be relative, end in a supported authored module extension, and match at least one
+module during compilation. A runtime value that was not among the discovered candidates rejects the
+import. Development watches the matched directory tree, so adding a new candidate invalidates the
+affected graph. Arbitrary computed specifiers that do not use this template-literal form remain
+outside the statically discoverable graph.
+
 ### Package CSS and static assets
 
 Applications can import stylesheets exposed through package `exports` in the same way as local
@@ -162,9 +182,10 @@ from a connected client component.
 
 Navigation context is intended for compact UI state that must survive back/forward navigation but
 does not belong in the public URL. It must be a JSON-safe object and is limited to 8 KiB after UTF-8
-serialization. Evolit includes it in browser, response, and segment cache identity so the same URL
-cannot reuse markup rendered for a different context. Invalid context is rejected at the client
-boundary; malformed context received by the server is ignored.
+serialization. Evolit includes it in browser and response-cache identity. Segment caching and delta
+identity track only the top-level context keys each layout or page reads, so unrelated context
+changes preserve mounted layouts while consumers still update. Invalid context is rejected at the
+client boundary; malformed context received by the server is ignored.
 
 Client components can also read the active route state with browser-only hooks:
 
@@ -300,6 +321,32 @@ server components and helpers that do not receive route props directly. It retur
 Reading `getRouteState().url` has the same dynamic-rendering semantics as `requestUrl()`; reading
 `params` and `searchParams` participates in the normal segment-cache key tracking.
 
+## Server Setup
+
+Server integrations that need one-time application setup can be registered with
+`server.setup`. A module specifier is compiled as part of the server graph, so the
+setup may be authored in JavaScript or TypeScript:
+
+```js
+// evolit.config.js
+export default {
+  server: {
+    setup: "./src/server/setup.ts",
+  },
+};
+```
+
+The module exports `setup` (or a default function). Evolit invokes it once per
+runtime and once before build-time prerendering with `{ projectRoot, mode }`.
+It may return a cleanup function or `{ dispose() }`; runtime cleanup runs from
+`runtime.close()`.
+
+When `@litsx/urql` is installed, Evolit opens its SSR resource around the whole
+route render and supplies `{ request, responseHeaders }`. Request-derived URQL
+configuration therefore stays isolated per render, extracted SSR data is read
+before the scope closes, and integration response headers are included before
+the response is cached.
+
 ## Extensions
 
 Optional integrations are configured explicitly in `evolit.config.js`. Core only coordinates their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -71,7 +71,7 @@
     "ws": "^8.18.3"
   },
   "peerDependencies": {
-    "@litsx/urql": "^0.3.0"
+    "@litsx/urql": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@litsx/urql": {

package/src/build.js

@@ -51,7 +51,13 @@ import {
 import { serializeRouteCachePolicy } from "./route-config.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { ensureDirectory, writeJson } from "./fs-utils.js";
-import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
+import {
+  appendSsrUrqlData,
+  applySsrUrqlRequestContext,
+  createSsrUrqlRequestContext,
+  runWithOptionalSsrUrqlScope,
+} from "./urql-ssr.js";
+import { runServerSetup } from "./server-setup.js";
 
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
@@ -157,6 +163,11 @@ async function writeDeploymentRuntimeEntry(buildRoot) {
 
 export async function buildProject(projectRoot, options = {}) {
   const evolitConfig = await loadEvolitConfig(projectRoot);
+  const serverSetupCleanup = await runServerSetup({
+    projectRoot,
+    mode: "production",
+    evolitConfig,
+  });
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
   const packageClientSpecifiers = new Set(
@@ -541,23 +552,32 @@ export async function buildProject(projectRoot, options = {}) {
       seenPrerenderTargets.add(targetPathname);
 
       const targetRequest = new Request(`http://evolit.local${targetPathname}`);
-      const { routeResult, response } = await runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+      const urqlRequestContext = createSsrUrqlRequestContext(targetRequest);
+      const { routeResult, response } = await runWithOptionalSsrUrqlScope(urqlRequestContext, async (urqlAdapter) => {
         const resolvedRouteResult = await routeResolver.resolveRequest(targetRequest);
         if (resolvedRouteResult.type !== "route" || resolvedRouteResult.cachePolicy.mode === "dynamic") {
           return { routeResult: resolvedRouteResult, response: null };
         }
 
         const renderedResponse = await renderRouteTreeWithAdapter(resolvedRouteResult, ssrAdapter);
+        const responseWithData = urqlAdapter
+          ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
+          : renderedResponse;
         return {
           routeResult: resolvedRouteResult,
-          response: urqlAdapter
-            ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
-            : renderedResponse,
+          response: applySsrUrqlRequestContext(
+            resolvedRouteResult,
+            responseWithData,
+            urqlRequestContext,
+          ),
         };
       });
       if (!response) {
         continue;
       }
+      if (routeResult.cachePolicy.mode === "dynamic") {
+        continue;
+      }
       if (response.status !== 200) {
         continue;
       }
@@ -656,5 +676,7 @@ export async function buildProject(projectRoot, options = {}) {
   await writeJson(path.join(buildRoot, DEPLOY_ASSETS_MANIFEST_FILENAME), deployAssets);
   await writeJson(path.join(buildRoot, DEPLOY_SERVER_MANIFEST_FILENAME), deployServer);
 
+  await serverSetupCleanup?.();
+
   return manifestPath;
 }

package/src/compiler.js

@@ -20,6 +20,7 @@ import { ensureDirectory } from "./fs-utils.js";
 const MODULE_SPECIFIER_PATTERN =
   /\b(?:import|export)\s+(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
 const CSS_DEPENDENCY_PATTERN = /(?:@import\s+(?:url\(\s*)?["']([^"']+)["']\s*\)?|url\(\s*["']?([^"')]+)["']?\s*\))/g;
+const DYNAMIC_IMPORT_WILDCARD = "\u0000EVOLIT_DYNAMIC_IMPORT_WILDCARD\u0000";
 const RESOLVABLE_IMPORT_EXTENSIONS = [
   ...MODULE_EXTENSIONS,
   ...STATIC_ASSET_EXTENSIONS,
@@ -388,17 +389,30 @@ function getCompiledServerComponentExports(code, sourcePath) {
   return exports;
 }
 
-function collectImportedNamesBySpecifier(code, sourcePath) {
-  const sourceFile = ts.createSourceFile(sourcePath, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+function analyzeModuleReferences(code, sourcePath, scriptKind = ts.ScriptKind.JS) {
+  const sourceFile = ts.createSourceFile(sourcePath, code, ts.ScriptTarget.Latest, true, scriptKind);
   const bySpecifier = new Map();
+  const staticReferences = [];
+  const dynamicReferences = [];
   const add = (specifier, name) => {
     const names = bySpecifier.get(specifier) ?? new Set();
     names.add(name);
     bySpecifier.set(specifier, names);
   };
+  const addStaticReference = (node, importedName = null) => {
+    const specifier = node.text;
+    staticReferences.push({
+      specifier,
+      start: node.getStart(sourceFile) + 1,
+      end: node.end - 1,
+    });
+    if (importedName) add(specifier, importedName);
+  };
+
   for (const statement of sourceFile.statements) {
-    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier)) {
       const specifier = statement.moduleSpecifier.text;
+      addStaticReference(statement.moduleSpecifier);
       if (statement.importClause?.name) add(specifier, "default");
       if (statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)) {
         for (const element of statement.importClause.namedBindings.elements) {
@@ -408,9 +422,10 @@ function collectImportedNamesBySpecifier(code, sourcePath) {
     } else if (
       ts.isExportDeclaration(statement)
       && statement.moduleSpecifier
-      && ts.isStringLiteral(statement.moduleSpecifier)
+      && ts.isStringLiteralLike(statement.moduleSpecifier)
     ) {
       const specifier = statement.moduleSpecifier.text;
+      addStaticReference(statement.moduleSpecifier);
       if (!statement.exportClause) add(specifier, "*");
       else if (ts.isNamedExports(statement.exportClause)) {
         for (const element of statement.exportClause.elements) add(specifier, element.propertyName?.text ?? element.name.text);
@@ -421,13 +436,119 @@ function collectImportedNamesBySpecifier(code, sourcePath) {
     if (
       ts.isCallExpression(node)
       && node.expression.kind === ts.SyntaxKind.ImportKeyword
-      && node.arguments.length === 1
-      && ts.isStringLiteral(node.arguments[0])
-    ) add(node.arguments[0].text, "*");
+      && node.arguments.length >= 1
+    ) {
+      const argument = node.arguments[0];
+      if (ts.isStringLiteralLike(argument)) {
+        addStaticReference(argument, "*");
+      } else if (ts.isTemplateExpression(argument)) {
+        const staticParts = [
+          argument.head.text,
+          ...argument.templateSpans.map((span) => span.literal.text),
+        ];
+        dynamicReferences.push({
+          pattern: staticParts.join(DYNAMIC_IMPORT_WILDCARD),
+          displayPattern: staticParts.join("*"),
+          expressionText: code.slice(argument.getStart(sourceFile), argument.end),
+          optionsText: node.arguments.length > 1
+            ? code.slice(node.arguments[1].getStart(sourceFile), node.arguments.at(-1).end)
+            : null,
+          start: node.getStart(sourceFile),
+          end: node.end,
+        });
+      }
+    }
     ts.forEachChild(node, visit);
   };
   visit(sourceFile);
-  return bySpecifier;
+
+  return {
+    importedNamesBySpecifier: bySpecifier,
+    staticReferences,
+    dynamicReferences,
+  };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function createDynamicImportSegmentPattern(segment) {
+  return new RegExp(
+    `^${segment.split(DYNAMIC_IMPORT_WILDCARD).map(escapeRegExp).join("[^/]+")}$`,
+  );
+}
+
+async function discoverDynamicImportCandidates({
+  projectRoot,
+  sourcePath,
+  pattern,
+  displayPattern,
+  managedSourceRoots,
+}) {
+  const normalizedPattern = pattern.replaceAll("\\", "/");
+  if (!isRelativeSpecifier(normalizedPattern)) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} must be relative.`,
+    );
+  }
+  if (!MODULE_EXTENSIONS.some((extension) => normalizedPattern.endsWith(extension))) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} must end in a supported module extension.`,
+    );
+  }
+
+  const segments = normalizedPattern.split("/");
+  const firstDynamicSegment = segments.findIndex((segment) => segment.includes(DYNAMIC_IMPORT_WILDCARD));
+  if (firstDynamicSegment < 0) return { candidates: [], watchedDirectories: [] };
+
+  const scanRoot = path.resolve(path.dirname(sourcePath), ...segments.slice(0, firstDynamicSegment));
+  if (isPathOutsideManagedRoots(projectRoot, managedSourceRoots, scanRoot)) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} resolves outside the managed source roots.`,
+    );
+  }
+
+  const segmentPatterns = segments
+    .slice(firstDynamicSegment)
+    .map(createDynamicImportSegmentPattern);
+  const candidates = [];
+  const watchedDirectories = new Set();
+
+  async function visitDirectory(directory, segmentIndex) {
+    watchedDirectories.add(directory);
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return;
+      throw error;
+    }
+
+    const matcher = segmentPatterns[segmentIndex];
+    const isFinalSegment = segmentIndex === segmentPatterns.length - 1;
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!matcher.test(entry.name)) continue;
+      const candidatePath = path.join(directory, entry.name);
+      if (isFinalSegment) {
+        if (entry.isFile()) candidates.push(candidatePath);
+      } else if (entry.isDirectory()) {
+        await visitDirectory(candidatePath, segmentIndex + 1);
+      }
+    }
+  }
+
+  await visitDirectory(scanRoot, 0);
+  if (candidates.length === 0) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} did not match any modules.`,
+    );
+  }
+
+  return {
+    candidates,
+    watchedDirectories: [...watchedDirectories],
+  };
 }
 
 function createClientServerComponentImportError(entryPath, sourcePath, parents) {
@@ -841,18 +962,17 @@ async function rewriteRelativeSpecifiers({
   managedSourceRoots,
   serverExportsByModule,
   packageImports,
+  dynamicImportDirectories,
 }) {
   const magicSource = new MagicString(code);
   let didRewrite = false;
+  const moduleReferences = analyzeModuleReferences(code, sourcePath);
   const importedNamesBySpecifier = target === "client"
-    ? collectImportedNamesBySpecifier(code, sourcePath)
+    ? moduleReferences.importedNamesBySpecifier
     : new Map();
 
-  for (const match of code.matchAll(MODULE_SPECIFIER_PATTERN)) {
-    const specifier = match[1] ?? match[2] ?? null;
-    if (!specifier) {
-      continue;
-    }
+  for (const reference of moduleReferences.staticReferences) {
+    const { specifier } = reference;
 
     const aliasedImportPath = isBareSpecifier(specifier)
       ? await resolveProjectMappedImport(projectRoot, sourcePath, specifier)
@@ -996,18 +1116,99 @@ async function rewriteRelativeSpecifiers({
     ) {
       normalizedReplacement = `${normalizedReplacement}?${serverImportQuery}`;
     }
-    const quotedSpecifierIndex = match.index + match[0].indexOf(specifier);
     const replacementValue = normalizedReplacement.split(path.sep).join("/");
     if (replacementValue !== specifier) {
       didRewrite = true;
       magicSource.update(
-        quotedSpecifierIndex,
-        quotedSpecifierIndex + specifier.length,
+        reference.start,
+        reference.end,
         replacementValue,
       );
     }
   }
 
+  const dynamicImportHelpers = [];
+  for (const [index, reference] of moduleReferences.dynamicReferences.entries()) {
+    const discovery = await discoverDynamicImportCandidates({
+      projectRoot,
+      sourcePath,
+      pattern: reference.pattern,
+      displayPattern: reference.displayPattern,
+      managedSourceRoots,
+    });
+    discovery.watchedDirectories.forEach((directory) => dynamicImportDirectories.add(directory));
+
+    const cases = [];
+    for (const resolvedImportPath of discovery.candidates) {
+      const compiledImportPath = await compileModule(resolvedImportPath);
+      const serverExports = serverExportsByModule?.get(resolvedImportPath) ?? new Set();
+      if (target === "client" && serverExports.size > 0) {
+        throw new Error(
+          `Client module ${sourcePath} dynamically imports Server Component export(s) from ${resolvedImportPath}: `
+          + `${[...serverExports].join(", ")}. Split the server exports into a separate module.`,
+        );
+      }
+
+      const importerOutputPath = toOutputPath(projectRoot, outputRoot, sourcePath);
+      let replacementPath = path.relative(path.dirname(importerOutputPath), compiledImportPath);
+      if (!replacementPath.startsWith(".")) replacementPath = `./${replacementPath}`;
+      replacementPath = replacementPath.split(path.sep).join("/");
+      if (
+        target === "server"
+        && mode === "development"
+        && typeof serverImportQuery === "string"
+        && serverImportQuery.length > 0
+      ) {
+        replacementPath = `${replacementPath}?${serverImportQuery}`;
+      }
+
+      let sourceSpecifier = path.relative(path.dirname(sourcePath), resolvedImportPath)
+        .split(path.sep)
+        .join("/");
+      if (!sourceSpecifier.startsWith(".")) sourceSpecifier = `./${sourceSpecifier}`;
+      cases.push(
+        `    case ${JSON.stringify(sourceSpecifier)}: return import(${JSON.stringify(replacementPath)}${reference.optionsText ? ", options" : ""});`,
+      );
+
+      if (target === "client") {
+        const sourceMetadata = moduleMetadata.get(sourcePath) ?? {
+          moduleImports: new Set(),
+          vendorImports: new Set(),
+          styleImports: new Set(),
+          assetImports: new Set(),
+        };
+        sourceMetadata.moduleImports.add(
+          path.relative(outputRoot, compiledImportPath).split(path.sep).join("/"),
+        );
+        moduleMetadata.set(sourcePath, sourceMetadata);
+      }
+    }
+
+    let helperName = `__evolit_dynamic_import_${index}`;
+    while (code.includes(helperName)) helperName = `_${helperName}`;
+    const sourceModuleId = path.relative(projectRoot, sourcePath).split(path.sep).join("/");
+    const unknownImportPrefix = `Unknown dynamic import in ${sourceModuleId}: `;
+    dynamicImportHelpers.push([
+      `function ${helperName}(specifier${reference.optionsText ? ", options" : ""}) {`,
+      "  switch (specifier) {",
+      ...cases,
+      "    default:",
+      `      return Promise.reject(new Error(${JSON.stringify(unknownImportPrefix)} + specifier));`,
+      "  }",
+      "}",
+    ].join("\n"));
+    magicSource.update(
+      reference.start,
+      reference.end,
+      `${helperName}(${reference.expressionText}${reference.optionsText ? `, ${reference.optionsText}` : ""})`,
+    );
+    didRewrite = true;
+  }
+
+  if (dynamicImportHelpers.length > 0) {
+    magicSource.append(`\n\n${dynamicImportHelpers.join("\n\n")}\n`);
+  }
+
   const rewrittenCode = magicSource.toString();
   if (!sourceMaps || !didRewrite) {
     return {
@@ -1131,7 +1332,10 @@ export function invalidateDevelopmentCompilationCache(projectRoot, changedPaths
     const shouldInvalidate =
       normalizedChangedPaths == null ||
       !dependencies ||
-      [...dependencies].some((dependency) => normalizedChangedPaths.has(dependency));
+      [...dependencies.files].some((dependency) => normalizedChangedPaths.has(dependency)) ||
+      [...dependencies.directories].some((directory) =>
+        [...normalizedChangedPaths].some((changedPath) => !isPathOutsideProject(directory, changedPath))
+      );
     if (shouldInvalidate) {
       developmentGraphCache.delete(key);
       developmentGraphDependencies.delete(key);
@@ -1163,6 +1367,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
   const moduleMetadata = new Map();
   const serverExportsByModule = new Map();
   const packageImports = new Set();
+  const dynamicImportDirectories = new Set();
   const serverImportQuery = target === "server" && mode === "development"
     ? `t=${Date.now()}`
     : null;
@@ -1233,6 +1438,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
       managedSourceRoots,
       serverExportsByModule,
       packageImports,
+      dynamicImportDirectories,
     });
 
     await fs.writeFile(outputPath, rewritten.code, "utf8");
@@ -1262,6 +1468,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
     entrypoint: await compileModule(entryPath),
     outputRoot,
     sourceFiles: [...new Set([...visited.keys(), ...staticAssetFiles])],
+    watchedDirectories: [...dynamicImportDirectories],
     packageImports: [...packageImports].sort(),
   };
 }
@@ -1286,7 +1493,10 @@ export async function compileModuleGraph(entryPath, options = {}) {
     developmentGraphCache.set(cacheKey, pendingCompile);
     pendingCompile.then((result) => {
       if (developmentGraphCache.get(cacheKey) === pendingCompile) {
-        developmentGraphDependencies.set(cacheKey, new Set(result.sourceFiles));
+        developmentGraphDependencies.set(cacheKey, {
+          files: new Set(result.sourceFiles),
+          directories: new Set(result.watchedDirectories ?? []),
+        });
       }
     }, () => {});
   }
@@ -1425,15 +1635,15 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
     if (isComponent && isServer) boundaries.add(sourcePath);
     if (!traverseNonBoundary) return;
     const componentImportSpecifiers = collectComponentImportSpecifiers(source, sourcePath);
-    for (const match of source.matchAll(MODULE_SPECIFIER_PATTERN)) {
-      const specifier = match[1] ?? match[2];
-      if (!specifier) continue;
+    const moduleReferences = analyzeModuleReferences(source, sourcePath, ts.ScriptKind.TSX);
+
+    async function visitResolvedSpecifier(specifier) {
       const aliasResolved = isBareSpecifier(specifier)
         ? await resolveProjectMappedImport(projectRoot, sourcePath, specifier)
         : null;
       const resolved = aliasResolved
         ?? await resolveProjectModuleSpecifier(projectRoot, sourcePath, specifier);
-      if (!resolved) continue;
+      if (!resolved) return;
       if (shouldCompileModule(resolved)) {
         if (isBareSpecifier(specifier) && aliasResolved == null) {
           if (componentImportSpecifiers.has(specifier)) {
@@ -1450,6 +1660,21 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
         assets.add(resolved);
       }
     }
+
+    for (const reference of moduleReferences.staticReferences) {
+      await visitResolvedSpecifier(reference.specifier);
+    }
+    for (const reference of moduleReferences.dynamicReferences) {
+      const discovery = await discoverDynamicImportCandidates({
+        projectRoot,
+        sourcePath,
+        pattern: reference.pattern,
+        displayPattern: reference.displayPattern,
+      });
+      for (const candidate of discovery.candidates) {
+        await visit(candidate, true);
+      }
+    }
   }
 
   for (const entryPath of entryPaths) await visit(entryPath);

package/src/deployment-runtime.js

@@ -41,12 +41,18 @@ import {
 } from "./response-cache.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { createNavigationResponseFromDocument } from "./route-segments.js";
-import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
+import {
+  appendSsrUrqlData,
+  applySsrUrqlRequestContext,
+  createSsrUrqlRequestContext,
+  runWithOptionalSsrUrqlScope,
+} from "./urql-ssr.js";
 import {
   getExtensionClientDescriptors,
   resolveEvolitExtensions,
   runRequestExtensions,
 } from "./extensions.js";
+import { runServerSetup } from "./server-setup.js";
 
 function isBarePackageModuleId(value) {
   return typeof value === "string"
@@ -882,7 +888,8 @@ export async function createRequestRenderer({
       return effectiveRouteResolver.resolveRoutePolicy(request, options);
     },
     async renderRoute(request, routePolicyResult = null, options = {}) {
-      return runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+      const urqlRequestContext = createSsrUrqlRequestContext(request);
+      return runWithOptionalSsrUrqlScope(urqlRequestContext, async (urqlAdapter) => {
         const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
         let resolvedRoutePolicyResult = routePolicyResult;
         if (shouldPrepareBeforeResolve) {
@@ -895,9 +902,14 @@ export async function createRequestRenderer({
           await this.prepareRouteClientArtifacts(routeResult);
         }
         const renderedResponse = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
-        const response = urqlAdapter
+        const responseWithData = urqlAdapter
           ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
           : renderedResponse;
+        const response = applySsrUrqlRequestContext(
+          routeResult,
+          responseWithData,
+          urqlRequestContext,
+        );
         return {
           routeResult,
           response,
@@ -921,8 +933,10 @@ export async function createDeploymentRuntime({
   routeResolver,
   onDevelopmentEvent,
   managedSourceRoots,
+  evolitConfig: configuredEvolitConfig,
 } = {}) {
-  const evolitConfig = await loadEvolitConfig(projectRoot);
+  const evolitConfig = configuredEvolitConfig ?? await loadEvolitConfig(projectRoot);
+  const serverSetupCleanup = await runServerSetup({ projectRoot, mode, evolitConfig });
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientSpecifiers = getExtensionClientDescriptors(extensions).map((descriptor) => descriptor.module);
   const effectiveManagedSourceRoots = managedSourceRoots
@@ -1072,6 +1086,7 @@ export async function createDeploymentRuntime({
       if (revalidationTasks) {
         await Promise.all(revalidationTasks.values());
       }
+      await serverSetupCleanup?.();
     },
   };
 }

package/src/navigation-client.js

@@ -194,6 +194,79 @@ function syncDocumentState(nextState, documentRef) {
   if (script) script.textContent = JSON.stringify(nextState);
 }
 
+function readElementAttributes(element) {
+  return Object.fromEntries([...element.attributes].map((attribute) => [
+    attribute.name,
+    attribute.value,
+  ]));
+}
+
+function isRootBodyProjection(segment, projection) {
+  return segment?.kind === "layout"
+    && segment?.depth === 0
+    && typeof projection?.html === "string"
+    && /<body(?:\s|>)/iu.test(projection.html);
+}
+
+function parseRootBodyProjection(projectionHtml, documentRef) {
+  const DOMParserConstructor = documentRef.defaultView?.DOMParser ?? globalThis.DOMParser;
+  if (typeof DOMParserConstructor !== "function") return null;
+  return new DOMParserConstructor().parseFromString(projectionHtml, "text/html").body;
+}
+
+function collectRouteRuntimeScripts(root) {
+  const scripts = [...root.querySelectorAll("script")];
+  return scripts.filter((script) =>
+    script.id === "__EVOLIT_ROUTE__"
+    || script.id === "__EVOLIT_DOCUMENT__"
+    || script.id === "__LITSX_HYDRATION__"
+    || script.hasAttribute("data-evolit-live-reload")
+    || (script.type === "module" && (
+      script.textContent?.includes("getNavigation")
+      || script.textContent?.includes("hydratePage")
+    )),
+  );
+}
+
+function replaceRootBodyProjection({
+  bodyProjection,
+  delta,
+  documentRef,
+  fragment,
+  target,
+}) {
+  const body = documentRef.body;
+  if (!body || !bodyProjection) return false;
+
+  const authoredAttributes = readElementAttributes(bodyProjection);
+  const managedAttributes = normalizeManagedAttributes(delta.document?.bodyAttributes);
+  syncElementAttributes(
+    body,
+    readElementAttributes(body),
+    { ...authoredAttributes, ...managedAttributes },
+  );
+
+  const runtimeScripts = collectRouteRuntimeScripts(documentRef);
+  body.replaceChildren(target.start, fragment, target.end, ...runtimeScripts);
+
+  // HTML parsing can leave nodes from an authored root <body> beside the live
+  // body. Once the stable body owns the committed projection and runtime
+  // scripts, discard only those invalid element siblings.
+  for (const element of [...documentRef.documentElement.children]) {
+    if (element !== documentRef.head && element !== body) element.remove();
+  }
+  return true;
+}
+
+function syncRouteStateScripts(delta, documentRef) {
+  const routeScript = documentRef.getElementById("__EVOLIT_ROUTE__");
+  if (routeScript) routeScript.textContent = JSON.stringify(delta.route);
+  const hydrationScript = documentRef.getElementById("__LITSX_HYDRATION__");
+  if (hydrationScript && delta.hydrationData) {
+    hydrationScript.textContent = JSON.stringify(delta.hydrationData);
+  }
+}
+
 function versionClientImport(specifier, version) {
   if (!version || typeof specifier !== "string") return specifier;
   const url = new URL(specifier, globalThis.location?.href ?? "http://evolit.local/");
@@ -260,9 +333,18 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
     throwIfAborted(signal);
     const projection = next.projections[offset] ?? next.projections[0];
     if (!projection) continue;
-    const template = documentRef.createElement("template");
-    template.innerHTML = projection.html;
-    const fragment = template.content;
+    const bodyProjection = isRootBodyProjection(next, projection)
+      ? parseRootBodyProjection(projection.html, documentRef)
+      : null;
+    const fragment = documentRef.createDocumentFragment();
+    if (bodyProjection) {
+      for (const script of collectRouteRuntimeScripts(bodyProjection)) script.remove();
+      fragment.append(...bodyProjection.childNodes);
+    } else {
+      const template = documentRef.createElement("template");
+      template.innerHTML = projection.html;
+      fragment.append(template.content);
+    }
     materializeDeclarativeShadowDom(fragment);
     // Restore opaque SSR forwarded refs while the fragment is detached, before
     // its custom elements upgrade on insertion.
@@ -279,11 +361,19 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
       roots.map(({ root, element }) => ({ ...root, element })),
       delta.hydrationData,
     );
-    const range = documentRef.createRange();
-    range.setStartAfter(target.start);
-    range.setEndBefore(target.end);
-    range.deleteContents();
-    range.insertNode(fragment);
+    if (!replaceRootBodyProjection({
+      bodyProjection,
+      delta,
+      documentRef,
+      fragment,
+      target,
+    })) {
+      const range = documentRef.createRange();
+      range.setStartAfter(target.start);
+      range.setEndBefore(target.end);
+      range.deleteContents();
+      range.insertNode(fragment);
+    }
     insertedRoots.push(...roots);
     target.start.data = `evolit:segment:start:${next.id}`;
     target.end.data = `evolit:segment:end:${next.id}`;
@@ -292,8 +382,7 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
   // document to point persistent layout refs at the new target, or clear them
   // when the replacement page no longer exposes one.
   prepareForwardedRefs(documentRef);
-  const script = documentRef.getElementById("__EVOLIT_ROUTE__");
-  if (script) script.textContent = JSON.stringify(delta.route);
+  syncRouteStateScripts(delta, documentRef);
   if (delta.title) documentRef.title = delta.title;
   for (const { root, element } of insertedRoots) {
     throwIfAborted(signal);

package/src/render.js

@@ -295,6 +295,67 @@ function createTrackedRouteValues(values) {
   };
 }
 
+function createTrackedNavigationContext(values) {
+  const tracked = createTrackedRouteValues(values ?? {});
+  let accessed = false;
+
+  return {
+    value: values == null ? null : tracked.value,
+    read() {
+      accessed = true;
+      return values == null ? null : tracked.value;
+    },
+    profile() {
+      return { accessed, ...tracked.profile() };
+    },
+  };
+}
+
+function createTrackedSegmentProps(
+  trackedParams,
+  trackedSearchParams,
+  trackedNavigationContext,
+  props,
+) {
+  const result = {
+    params: trackedParams.value,
+    searchParams: trackedSearchParams.value,
+    ...props,
+  };
+  Object.defineProperty(result, "navigationContext", {
+    enumerable: true,
+    get: () => trackedNavigationContext.read(),
+  });
+  return result;
+}
+
+function createSegmentDependencyProfile(
+  trackedParams,
+  trackedSearchParams,
+  trackedNavigationContext,
+) {
+  return {
+    params: trackedParams.profile(),
+    searchParams: trackedSearchParams.profile(),
+    navigationContext: trackedNavigationContext.profile(),
+  };
+}
+
+function selectTrackedValues(profile, values) {
+  const normalized = profile ?? { all: false, keys: [] };
+  return Object.fromEntries(
+    (normalized.all ? Object.keys(values ?? {}) : normalized.keys ?? [])
+      .sort()
+      .map((key) => [key, values?.[key]]),
+  );
+}
+
+function selectTrackedNavigationContext(profile, navigationContext) {
+  if (!profile?.accessed) return undefined;
+  if (navigationContext == null) return null;
+  return selectTrackedValues(profile, navigationContext);
+}
+
 function createSegmentCacheKey(
   segment,
   idPrefix,
@@ -303,30 +364,26 @@ function createSegmentCacheKey(
   searchParams,
   navigationContext,
 ) {
-  const select = (values) => Object.fromEntries(
-    (profile.all ? Object.keys(values) : profile.keys)
-      .sort()
-      .map((key) => [key, values[key]]),
-  );
   return JSON.stringify({
     modulePath: segment.modulePath,
     idPrefix,
-    params: select(params),
-    searchParams: select(searchParams),
-    navigationContext: navigationContext ?? null,
+    params: selectTrackedValues(profile.params, params),
+    searchParams: selectTrackedValues(profile.searchParams, searchParams),
+    navigationContext: selectTrackedNavigationContext(
+      profile.navigationContext,
+      navigationContext,
+    ),
   });
 }
 
 function createSegmentInputKey(profile, params, searchParams, navigationContext) {
-  const select = (values) => Object.fromEntries(
-    (profile.all ? Object.keys(values) : profile.keys)
-      .sort()
-      .map((key) => [key, values[key]]),
-  );
   return JSON.stringify({
-    params: select(params),
-    searchParams: select(searchParams),
-    navigationContext: navigationContext ?? null,
+    params: selectTrackedValues(profile.params, params),
+    searchParams: selectTrackedValues(profile.searchParams, searchParams),
+    navigationContext: selectTrackedNavigationContext(
+      profile.navigationContext,
+      navigationContext,
+    ),
   });
 }
 
@@ -457,18 +514,37 @@ async function renderSegmentedComponentTree(
     const idPrefix = `${segment.id}-p${projectionPath.join("-") || "0"}`;
 
     if (index === layoutComponents.length) {
-      const pageValue = await component({
-        params: requestContext.params,
-        searchParams: requestContext.searchParams,
-        navigationContext: requestContext.navigationContext,
-        request,
-        ...extraProps,
-      }, incomingRef);
+      const trackedParams = createTrackedRouteValues(requestContext.params);
+      const trackedSearchParams = createTrackedRouteValues(requestContext.searchParams);
+      const trackedNavigationContext = createTrackedNavigationContext(
+        requestContext.navigationContext,
+      );
+      const pageValue = await runWithRouteState(requestContext, {
+        params: trackedParams.value,
+        searchParams: trackedSearchParams.value,
+        navigationContext: trackedNavigationContext.value,
+        trackNavigationContext: () => trackedNavigationContext.read(),
+      }, () => component(createTrackedSegmentProps(
+        trackedParams,
+        trackedSearchParams,
+        trackedNavigationContext,
+        { request, ...extraProps },
+      ), incomingRef));
       const pageResult = await renderToString(wrapRouteSegment(segment, pageValue), {
         assetResolver: options.assetResolver,
         context: { idPrefix },
       });
       pageResult.segmentModulePath = segment.modulePath;
+      segment.inputKey = createSegmentInputKey(
+        createSegmentDependencyProfile(
+          trackedParams,
+          trackedSearchParams,
+          trackedNavigationContext,
+        ),
+        requestContext.params,
+        requestContext.searchParams,
+        requestContext.navigationContext,
+      );
       results.push(pageResult);
       return pageResult.html;
     }
@@ -486,31 +562,36 @@ async function renderSegmentedComponentTree(
     if (!layoutResult) {
       const trackedParams = createTrackedRouteValues(requestContext.params);
       const trackedSearchParams = createTrackedRouteValues(requestContext.searchParams);
+      const trackedNavigationContext = createTrackedNavigationContext(
+        requestContext.navigationContext,
+      );
       const didUseDynamicRequestData = requestContext.didUseDynamicRequestData;
       layoutResult = await runWithRouteState(requestContext, {
         params: trackedParams.value,
         searchParams: trackedSearchParams.value,
+        navigationContext: trackedNavigationContext.value,
+        trackNavigationContext: () => trackedNavigationContext.read(),
       }, async () => {
-        const layoutValue = await layoutComponents[index]({
-          params: trackedParams.value,
-          searchParams: trackedSearchParams.value,
-          navigationContext: requestContext.navigationContext,
-          request,
-          children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
-        }, incomingRef);
+        const layoutValue = await layoutComponents[index](createTrackedSegmentProps(
+          trackedParams,
+          trackedSearchParams,
+          trackedNavigationContext,
+          {
+            request,
+            children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
+          },
+        ), incomingRef);
         return renderToString(wrapRouteSegment(segment, layoutValue), {
           assetResolver: options.assetResolver,
           context: { idPrefix },
         });
       });
       layoutResult.segmentModulePath = segment.modulePath;
-      profile = {
-        all: trackedParams.profile().all || trackedSearchParams.profile().all,
-        keys: [...new Set([
-          ...trackedParams.profile().keys,
-          ...trackedSearchParams.profile().keys,
-        ])].sort(),
-      };
+      profile = createSegmentDependencyProfile(
+        trackedParams,
+        trackedSearchParams,
+        trackedNavigationContext,
+      );
       if (!didUseDynamicRequestData && !requestContext.didUseDynamicRequestData) {
         options.segmentCache?.set(
           segment,

package/src/request-context.js

@@ -175,7 +175,10 @@ export function getRouteState() {
     },
     navigationContext: {
       enumerable: true,
-      value: context.navigationContext,
+      get() {
+        trackedState?.trackNavigationContext?.();
+        return routeState.navigationContext;
+      },
     },
   });
 

package/src/server-setup.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { importCompiledModule, resolveProjectModuleSpecifier } from "./compiler.js";
+
+function resolveSetupExport(moduleRecord, setupPath) {
+  const setup = moduleRecord.setup ?? moduleRecord.default;
+  if (typeof setup !== "function") {
+    throw new TypeError(
+      `Expected server setup module ${JSON.stringify(setupPath)} to export a setup function or a default function.`,
+    );
+  }
+  return setup;
+}
+
+function normalizeCleanup(result) {
+  if (result == null) return null;
+  if (typeof result === "function") return result;
+  if (typeof result === "object" && typeof result.dispose === "function") {
+    return () => result.dispose();
+  }
+  throw new TypeError("Evolit server setup must return nothing, a cleanup function, or an object with dispose().");
+}
+
+/** Runs the application server bootstrap once for a build or runtime instance. */
+export async function runServerSetup({ projectRoot, mode, evolitConfig = {} }) {
+  const serverConfig = evolitConfig.server;
+  if (serverConfig == null) return null;
+  if (!serverConfig || typeof serverConfig !== "object" || Array.isArray(serverConfig)) {
+    throw new TypeError("Expected server in evolit.config.js to be an object.");
+  }
+
+  const configuredSetup = serverConfig.setup;
+  if (configuredSetup == null) return null;
+
+  let setup = configuredSetup;
+  if (typeof configuredSetup === "string") {
+    if (configuredSetup.length === 0) {
+      throw new TypeError("Expected server.setup to be a non-empty module specifier.");
+    }
+    const setupPath = await resolveProjectModuleSpecifier(
+      projectRoot,
+      path.join(projectRoot, "evolit.config.js"),
+      configuredSetup,
+    );
+    if (!setupPath) {
+      throw new Error(`Unable to resolve configured server setup ${JSON.stringify(configuredSetup)}.`);
+    }
+    const moduleRecord = await importCompiledModule(setupPath, {
+      projectRoot,
+      mode,
+      sourceMaps: mode === "development",
+      target: "server",
+    });
+    setup = resolveSetupExport(moduleRecord, configuredSetup);
+  }
+
+  if (typeof setup !== "function") {
+    throw new TypeError("Expected server.setup in evolit.config.js to be a function or module specifier.");
+  }
+
+  return normalizeCleanup(await setup({
+    projectRoot,
+    mode,
+  }));
+}

package/src/server.js

@@ -214,6 +214,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     responseCacheRuntime,
     onDevelopmentEvent: reportDevelopmentEvent,
     managedSourceRoots,
+    evolitConfig,
   });
   const port = getPort(explicitPort);
   const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;

package/src/urql-ssr.js

@@ -26,7 +26,18 @@ export async function getSsrUrqlAdapter() {
  * Evolit owns only lifecycle here; client creation and URQL configuration stay
  * entirely in the application and @litsx/urql.
  */
-export async function runWithOptionalSsrUrqlScope(callback, options = {}) {
+export async function runWithOptionalSsrUrqlScope(
+  contextOrCallback,
+  callbackOrOptions = {},
+  maybeOptions = {},
+) {
+  const hasRequestContext = typeof contextOrCallback !== "function";
+  const requestContext = hasRequestContext ? contextOrCallback : null;
+  const callback = hasRequestContext ? callbackOrOptions : contextOrCallback;
+  const options = hasRequestContext ? maybeOptions : callbackOrOptions;
+  if (typeof callback !== "function") {
+    throw new TypeError("runWithOptionalSsrUrqlScope() expects a render callback.");
+  }
   const adapter = Object.hasOwn(options, "adapter")
     ? options.adapter
     : await getSsrUrqlAdapter();
@@ -34,7 +45,61 @@ export async function runWithOptionalSsrUrqlScope(callback, options = {}) {
     return callback(null);
   }
 
-  return adapter.runWithUrqlScope(() => callback(adapter));
+  return hasRequestContext
+    ? adapter.runWithUrqlScope(requestContext, () => callback(adapter))
+    : adapter.runWithUrqlScope(() => callback(adapter));
+}
+
+/** Creates the HTTP context passed to a request-scoped URQL resource factory. */
+export function createSsrUrqlRequestContext(request) {
+  let didUseRequestData = false;
+  const trackedRequest = new Proxy(request, {
+    get(target, property) {
+      if (property !== "constructor" && property !== Symbol.toStringTag) {
+        didUseRequestData = true;
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  const responseHeaders = new Headers();
+  return {
+    request: trackedRequest,
+    responseHeaders,
+    didUseDynamicRequestData() {
+      return didUseRequestData || !responseHeaders.entries().next().done;
+    },
+  };
+}
+
+function responseHeadersToObject(headers) {
+  const values = Object.fromEntries(headers.entries());
+  if (typeof headers.getSetCookie === "function") {
+    const cookies = headers.getSetCookie();
+    if (cookies.length > 0) values["set-cookie"] = cookies;
+  }
+  return values;
+}
+
+/** Applies request-resource response state before Evolit caches the render. */
+export function applySsrUrqlRequestContext(routeResult, response, context) {
+  if (!context) return response;
+  const urqlHeaders = responseHeadersToObject(context.responseHeaders);
+  if (context.didUseDynamicRequestData()) {
+    routeResult.cachePolicy = { mode: "dynamic" };
+  }
+  if (Object.keys(urqlHeaders).length === 0) return response;
+  routeResult.responseHeaders = {
+    ...(routeResult.responseHeaders ?? {}),
+    ...urqlHeaders,
+  };
+  return {
+    ...response,
+    headers: {
+      ...(response.headers ?? {}),
+      ...urqlHeaders,
+    },
+  };
 }
 
 function escapeJsonForHtml(value) {