evolit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/deployment-runtime.js

@@ -1,22 +1,29 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { compileModuleGraph } from "./compiler.js";
+import {
+  compileModuleGraph,
+  invalidateDevelopmentCompilationCache,
+} from "./compiler.js";
 import {
   collectTransitiveAssetPreloads,
   collectTransitiveStyleUrls,
   createAssetResolver,
   createHydrationBootstrap,
   createStaticAssetPublicUrlMap,
+  buildSharedVendorRuntime,
   emitBundledClientAssetsWithState,
   getAssetByPublicUrl,
   getSharedOutputRoot,
   normalizeHydrationDataForClient,
   normalizeClientAssetManifest,
+  resetDevelopmentAssetCaches,
+  resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   resolveBrowserPackageAssetFilePath,
   rewriteHydrationDataScript,
 } from "./client-assets.js";
 import { loadEvolitConfig } from "./config.js";
+import { DEV_DIRECTORY, INTERNAL_DIRECTORY } from "./constants.js";
 import { createRouteResolver } from "./render.js";
 import {
   createCachedRouteResponse,
@@ -25,6 +32,7 @@ import {
   resolveResponseCacheRuntime,
 } from "./response-cache.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
+import { createNavigationResponseFromDocument } from "./route-segments.js";
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
   [".svg", "image/svg+xml"],
@@ -208,7 +216,14 @@ export function createResponseCacheController({ responseCacheRuntime }) {
   };
 }
 
-export async function createRequestRenderer({ projectRoot, mode, assetManifest, routeResolver, responseCacheRuntime }) {
+export async function createRequestRenderer({
+  projectRoot,
+  mode,
+  assetManifest,
+  routeResolver,
+  responseCacheRuntime,
+  onDevelopmentEvent,
+}) {
   let currentAssetManifest = normalizeClientAssetManifest(assetManifest);
   let currentAssetResolver = createAssetResolver(projectRoot, {
     assetManifest: currentAssetManifest,
@@ -218,25 +233,70 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
     mode,
     "@litsx/ssr/hydration",
   );
+  let currentNavigationModuleUrl = await resolveSharedVendorModuleUrl(
+    projectRoot,
+    mode,
+    "evolit/navigation",
+  );
   const devBundledEntries = new Set();
+  const devPreparedClientModules = new Set();
+  const devClientModuleDependencies = new Map();
   let devRollupCache = null;
+  let devClientAssetWork = Promise.resolve();
+  const developmentMetrics = {
+    clientArtifactBuilds: 0,
+    clientArtifactCacheHits: 0,
+    invalidations: 0,
+    selectivelyInvalidatedClientEntries: 0,
+  };
   const usesFrameworkRouteResolver = !routeResolver;
+  let sharedSegmentRenderCache = null;
+
+  function enqueueDevClientAssetWork(work) {
+    const nextWork = devClientAssetWork.then(work, work);
+    devClientAssetWork = nextWork.catch(() => {});
+    return nextWork;
+  }
+
+  function reportDevelopmentEvent(event) {
+    if (mode === "development" && typeof onDevelopmentEvent === "function") {
+      onDevelopmentEvent(event);
+    }
+  }
+
+  function getDevClientModuleKey(clientModule) {
+    return path.resolve(projectRoot, clientModule);
+  }
   async function createFrameworkRouteResolver() {
-    return createRouteResolver(projectRoot, mode, {
+    const resolver = await createRouteResolver(projectRoot, mode, {
+      onDevelopmentEvent,
+      segmentRenderCache: sharedSegmentRenderCache,
       getStaticAssetPublicUrls() {
         return createStaticAssetPublicUrlMap(currentAssetManifest);
       },
+      assetResolver(moduleId) {
+        return currentAssetResolver(moduleId);
+      },
     });
+    sharedSegmentRenderCache ??= resolver.segmentRenderCache;
+    return resolver;
   }
   let effectiveRouteResolver = routeResolver ?? await createFrameworkRouteResolver();
   const ssrAdapter = createSsrAdapter({
     assetResolver(moduleId) {
       return currentAssetResolver(moduleId);
     },
-    async resolveAdditionalHead({ result }) {
-      const clientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
-      const urls = currentAssetManifest
-        ? collectTransitiveAssetPreloads(clientImports, currentAssetManifest)
+    async resolveAdditionalHead({ routeResult, result }) {
+      const clientImports = [
+        ...(Array.isArray(result.clientImports) ? result.clientImports : []),
+        ...resolveRouteClientImports(routeResult, projectRoot, currentAssetManifest),
+      ];
+      const hydratedClientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+      const urls = currentAssetManifest && hydratedClientImports.length > 0
+        ? [...new Set([
+          ...hydratedClientImports,
+          ...collectTransitiveAssetPreloads(hydratedClientImports, currentAssetManifest),
+        ])]
         : [];
       const styleUrls = currentAssetManifest
         ? collectTransitiveStyleUrls(clientImports, currentAssetManifest)
@@ -246,23 +306,42 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
       }
 
       return [
-        ...urls.map((href) => `<link rel="modulepreload" href="${href}">`),
-        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
+        ...urls.map((href) => `<link rel="modulepreload" href="${href}" data-evolit-route-asset="preload">`),
+        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}" data-evolit-route-asset="style">`),
       ].join("\n");
     },
-    resolveBootstrap({ result }) {
+    resolveBootstrap({ routeResult, result }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        currentAssetManifest,
+      );
       return createHydrationBootstrap({
-        hydrationData: normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        hydrationData: normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
         assetResolver(moduleId) {
           return currentAssetResolver(moduleId);
         },
         hydrationModuleUrl: currentHydrationModuleUrl,
+        navigationModuleUrl: currentNavigationModuleUrl,
       });
     },
-    transformDocument({ result, document }) {
+    transformDocument({ routeResult, result, document }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        currentAssetManifest,
+      );
       return rewriteHydrationDataScript(
         document,
-        normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
       );
     },
   });
@@ -278,21 +357,52 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
       return effectiveRouteResolver;
     },
     responseCacheController,
-    async invalidateDevelopmentState() {
+    async invalidateDevelopmentState(changedPaths = null) {
       if (mode !== "development") {
         return;
       }
 
-      currentAssetManifest = null;
-      currentAssetResolver = createAssetResolver(projectRoot, {
-        assetManifest: currentAssetManifest,
-      });
-      devBundledEntries.clear();
-      devRollupCache = null;
+      return enqueueDevClientAssetWork(async () => {
+        developmentMetrics.invalidations += 1;
+        const normalizedChangedPaths = Array.isArray(changedPaths) && changedPaths.length > 0
+          ? new Set(changedPaths.map((changedPath) => path.resolve(changedPath)))
+          : null;
+        invalidateDevelopmentCompilationCache(projectRoot, changedPaths);
+        const affectedClientModules = normalizedChangedPaths == null
+          ? new Set(devPreparedClientModules)
+          : new Set(
+            [...devClientModuleDependencies]
+              .filter(([, dependencies]) =>
+                [...dependencies].some((dependency) => normalizedChangedPaths.has(dependency))
+              )
+              .map(([clientModule]) => clientModule),
+          );
+
+        if (affectedClientModules.size > 0 || normalizedChangedPaths == null) {
+          developmentMetrics.selectivelyInvalidatedClientEntries += affectedClientModules.size;
+          currentAssetManifest = null;
+          currentAssetResolver = createAssetResolver(projectRoot, {
+            assetManifest: currentAssetManifest,
+          });
+          devRollupCache = null;
+          for (const clientModule of affectedClientModules) {
+            devPreparedClientModules.delete(clientModule);
+            devClientModuleDependencies.delete(clientModule);
+          }
+        }
 
-      if (usesFrameworkRouteResolver) {
-        effectiveRouteResolver = await createFrameworkRouteResolver();
-      }
+        reportDevelopmentEvent({
+          type: "invalidated",
+          changedPathCount: normalizedChangedPaths?.size ?? null,
+          affectedClientEntryCount: affectedClientModules.size,
+        });
+
+        if (usesFrameworkRouteResolver) {
+          const segmentEntryCount = effectiveRouteResolver.invalidateSegmentCache?.(changedPaths) ?? 0;
+          reportDevelopmentEvent({ type: "segment-cache-invalidated", entryCount: segmentEntryCount });
+          effectiveRouteResolver = await createFrameworkRouteResolver();
+        }
+      });
     },
     async prepareRouteClientArtifacts(routeResult) {
       if (routeResult.type !== "route" && !routeResult.boundaryModule) {
@@ -304,19 +414,57 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
         ...(routeResult.boundaryModule ? [routeResult.boundaryModule] : []),
       ];
 
-      for (const clientModule of new Set(clientModules)) {
-        const clientBuild = await compileModuleGraph(clientModule, {
-          projectRoot,
-          mode,
-          sourceMaps: mode === "development",
-          target: "client",
-        });
-        devBundledEntries.add(
-          path.relative(clientBuild.outputRoot, clientBuild.entrypoint).split(path.sep).join("/"),
-        );
+      if (mode !== "development") {
+        for (const clientModule of new Set(clientModules)) {
+          await compileModuleGraph(clientModule, {
+            projectRoot,
+            mode,
+            sourceMaps: false,
+            target: "client",
+            onDevelopmentEvent,
+          });
+        }
+        return;
       }
 
-      if (mode === "development") {
+      return enqueueDevClientAssetWork(async () => {
+        let discoveredClientEntry = false;
+        for (const clientModule of new Set(clientModules)) {
+          const clientModuleKey = getDevClientModuleKey(clientModule);
+          if (devPreparedClientModules.has(clientModuleKey)) {
+            continue;
+          }
+
+          const clientBuild = await compileModuleGraph(clientModule, {
+            projectRoot,
+            mode,
+            sourceMaps: true,
+            target: "client",
+            onDevelopmentEvent,
+          });
+          devPreparedClientModules.add(clientModuleKey);
+          devClientModuleDependencies.set(
+            clientModuleKey,
+            new Set(clientBuild.sourceFiles ?? [clientModuleKey]),
+          );
+          devBundledEntries.add(
+            path.relative(clientBuild.outputRoot, clientBuild.entrypoint).split(path.sep).join("/"),
+          );
+          discoveredClientEntry = true;
+        }
+
+        if (!discoveredClientEntry && currentAssetManifest) {
+          developmentMetrics.clientArtifactCacheHits += 1;
+          reportDevelopmentEvent({ type: "client-assets-cache-hit" });
+          return;
+        }
+
+        developmentMetrics.clientArtifactBuilds += 1;
+        const buildStartedAt = performance.now();
+        reportDevelopmentEvent({
+          type: "client-assets-building",
+          entryCount: devBundledEntries.size,
+        });
         const bundledClientAssets = await emitBundledClientAssetsWithState(projectRoot, {
           mode: "development",
           entryClientModules: devBundledEntries,
@@ -336,19 +484,25 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
           },
         ) ?? currentHydrationModuleUrl;
         devRollupCache = bundledClientAssets.rollupCache;
-      }
+        reportDevelopmentEvent({
+          type: "client-assets-ready",
+          durationMs: Math.round(performance.now() - buildStartedAt),
+          entryCount: devBundledEntries.size,
+        });
+      });
     },
     async resolveRoutePolicy(request) {
       return effectiveRouteResolver.resolveRoutePolicy(request);
     },
     async renderRoute(request, routePolicyResult = null) {
       const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
+      let resolvedRoutePolicyResult = routePolicyResult;
       if (shouldPrepareBeforeResolve) {
-        const resolvedRoutePolicyResult = routePolicyResult ?? await effectiveRouteResolver.resolveRoutePolicy(request);
+        resolvedRoutePolicyResult ??= await effectiveRouteResolver.resolveRoutePolicy(request);
         await this.prepareRouteClientArtifacts(resolvedRoutePolicyResult);
       }
 
-      const routeResult = await effectiveRouteResolver.resolveRequest(request);
+      const routeResult = await effectiveRouteResolver.resolveRequest(request, resolvedRoutePolicyResult);
       if (!shouldPrepareBeforeResolve || routeResult.boundaryModule) {
         await this.prepareRouteClientArtifacts(routeResult);
       }
@@ -361,6 +515,9 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
     get assetManifest() {
       return currentAssetManifest;
     },
+    get developmentMetrics() {
+      return mode === "development" ? { ...developmentMetrics } : null;
+    },
   };
 }
 
@@ -370,7 +527,26 @@ export async function createDeploymentRuntime({
   assetManifest,
   responseCacheRuntime,
   routeResolver,
+  onDevelopmentEvent,
 } = {}) {
+  function reportDevelopmentEvent(event) {
+    if (mode === "development" && typeof onDevelopmentEvent === "function") {
+      onDevelopmentEvent(event);
+    }
+  }
+
+  if (mode === "development") {
+    reportDevelopmentEvent({ type: "initializing" });
+    const developmentRoot = path.join(projectRoot, INTERNAL_DIRECTORY, DEV_DIRECTORY);
+    await fs.rm(developmentRoot, { recursive: true, force: true });
+    invalidateDevelopmentCompilationCache(projectRoot);
+    resetDevelopmentAssetCaches(projectRoot);
+    await buildSharedVendorRuntime(projectRoot, "development", {
+      additionalEntrySpecifiers: [],
+    });
+    reportDevelopmentEvent({ type: "vendor-runtime-ready" });
+  }
+
   const effectiveResponseCacheRuntime = responseCacheRuntime
     ?? await resolveResponseCacheRuntime(
       projectRoot,
@@ -378,8 +554,18 @@ export async function createDeploymentRuntime({
       await loadEvolitConfig(projectRoot),
     );
   const runtimeState = {
-    assetManifest: normalizeClientAssetManifest(assetManifest),
+    assetManifest: mode === "development" ? null : normalizeClientAssetManifest(assetManifest),
   };
+
+  function formatResponseForRequest(request, response) {
+    const representation = request.headers.get("accept")?.includes("application/vnd.evolit.navigation+json")
+      ? createNavigationResponseFromDocument(response)
+      : response;
+    // The same URL has an HTML document representation and a navigation
+    // delta representation. Tell intermediary HTTP caches that Accept selects
+    // between them.
+    return addNavigationVaryHeader(representation);
+  }
   const assets = createPublicAssetOrigin({
     projectRoot,
     mode,
@@ -393,18 +579,19 @@ export async function createDeploymentRuntime({
     assetManifest: runtimeState.assetManifest,
     responseCacheRuntime: effectiveResponseCacheRuntime,
     routeResolver,
+    onDevelopmentEvent,
   });
 
   return {
     assets,
     cache: renderer.responseCacheController,
     renderer,
-    async invalidateDevelopmentState() {
+    async invalidateDevelopmentState(changedPaths = null) {
       if (mode !== "development") {
         return;
       }
 
-      await renderer.invalidateDevelopmentState();
+      await renderer.invalidateDevelopmentState(changedPaths);
       if (typeof effectiveResponseCacheRuntime.store.clear === "function") {
         await effectiveResponseCacheRuntime.store.clear();
       }
@@ -422,7 +609,7 @@ export async function createDeploymentRuntime({
       const cachedResponse = await renderer.responseCacheController.read(request, routePolicyResult);
       if (cachedResponse) {
         if (cachedResponse.fresh) {
-          return cachedResponse.response;
+          return formatResponseForRequest(request, cachedResponse.response);
         }
 
         if (
@@ -446,12 +633,15 @@ export async function createDeploymentRuntime({
           revalidationTasks.set(cachedResponse.cacheKey, revalidationTask);
         }
 
-        return cachedResponse.response;
+        return formatResponseForRequest(request, cachedResponse.response);
       }
 
       const { routeResult, response } = await renderer.renderRoute(request, routePolicyResult);
       runtimeState.assetManifest = normalizeClientAssetManifest(renderer.assetManifest);
-      return renderer.responseCacheController.write(request, routeResult, response);
+      return formatResponseForRequest(
+        request,
+        await renderer.responseCacheController.write(request, routeResult, response),
+      );
     },
     async close() {
       const revalidationTasks = this.revalidationTasks;
@@ -461,3 +651,16 @@ export async function createDeploymentRuntime({
     },
   };
 }
+
+function addNavigationVaryHeader(response) {
+  if (!response?.headers) return response;
+  const fields = String(response.headers.vary ?? "")
+    .split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+  if (!fields.some((field) => field.toLowerCase() === "accept")) fields.push("accept");
+  return {
+    ...response,
+    headers: { ...response.headers, vary: fields.join(", ") },
+  };
+}

package/src/development-events.js

@@ -0,0 +1,96 @@
+import { terminal } from "./terminal.js";
+
+/**
+ * Creates the default development-event sink used by the CLI and dev server.
+ * Keeping presentation here lets integrations replace it with onDevelopmentEvent
+ * without losing any lifecycle, build, or request diagnostics.
+ */
+export function createDevelopmentEventReporter() {
+  return (event) => {
+    switch (event.type) {
+      case "server-starting":
+        console.log(`${terminal.cyan("▲")} ${terminal.bold("Evolit")} ${terminal.cyan(event.mode ?? "dev")}`);
+        break;
+      case "usage":
+        console.log(`${terminal.bold("Usage:")} evolit <directory>`);
+        console.log(`       evolit ${terminal.cyan("init")} <directory>`);
+        console.log(`       evolit ${terminal.cyan("<dev|build|start>")} [--port 3000]`);
+        break;
+      case "site-created":
+        console.log(`${terminal.green("✓")} Created evolit site: ${terminal.cyan(event.directory)}`);
+        break;
+      case "build-ready":
+        console.log(`${terminal.green("✓")} Built Evolit app: ${terminal.cyan(event.manifestPath)}`);
+        break;
+      case "initializing":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.yellow("○")} Preparing development runtime…`);
+        break;
+      case "vendor-runtime-ready":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.green("✓")} Vendor runtime ready.`);
+        break;
+      case "client-assets-building":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.magenta("○")} Compiling client assets (${event.entryCount} entries)…`);
+        break;
+      case "client-assets-ready":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.green("✓")} Client assets compiled in ${terminal.dim(`${event.durationMs}ms`)} (${event.entryCount} entries).`);
+        break;
+      case "client-assets-cache-hit":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.blue("●")} Client assets served from cache.`);
+        break;
+      case "segment-cache-hit":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.blue("●")} Reused route segment ${terminal.dim(event.modulePath)}.`);
+        break;
+      case "segment-cache-miss":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.magenta("○")} Rendering route segment ${terminal.dim(event.modulePath)} ${terminal.dim(`(${event.reason})`)}.`);
+        break;
+      case "segment-cache-invalidated":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Invalidated ${event.entryCount} cached route segments.`);
+        break;
+      case "invalidated":
+        console.log(
+          `${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Source change detected${event.changedPathCount == null ? "" : ` (${event.changedPathCount} files)`}; invalidated ${event.affectedClientEntryCount} client entries.`,
+        );
+        break;
+      case "unmanaged-import":
+        console.warn(
+          `${terminal.yellow("[evolit]")} ${terminal.yellow("⚠")} Unmanaged import ${terminal.cyan(JSON.stringify(event.resolvedImportPath))} from ${terminal.cyan(JSON.stringify(event.sourcePath))} is outside the project root. Evolit does not watch it; changes may not trigger a rebuild, and it may be unavailable in another checkout or deployment. It will be emitted under ${terminal.cyan("/_evolit/static/__unmanaged__/")}.`,
+        );
+        break;
+      case "server-ready":
+        console.log(`${terminal.green("✓")} Ready on ${terminal.cyan(`http://localhost:${event.port}`)}`);
+        break;
+      case "request": {
+        const statusColor = event.status >= 500
+          ? terminal.red
+          : event.status >= 400
+            ? terminal.yellow
+            : event.status >= 300
+              ? terminal.blue
+              : terminal.green;
+        console.log(
+          `${terminal.cyan("[evolit]")} ${terminal.dim(event.method)} ${event.pathname} ${statusColor(event.status)} in ${terminal.dim(`${event.durationMs}ms`)}${event.cacheState ? ` ${terminal.blue(`(${event.cacheState})`)}` : ""}`,
+        );
+        break;
+      }
+      case "request-error":
+        console.error(
+          `${terminal.red("[evolit]")} ${terminal.red("✖")} ${event.method} ${event.pathname} failed`,
+          event.error,
+        );
+        break;
+      case "fatal-error":
+        console.error(
+          `${terminal.red("[evolit]")} ${terminal.red("✖")} ${event.error instanceof Error ? event.error.stack ?? event.error.message : String(event.error)}`,
+        );
+        break;
+      case "route-error":
+        console.error(
+          `${terminal.red("[evolit]")} ${terminal.red("✖")} Route rendering failed ${terminal.dim(`(${event.digest})`)} at ${terminal.cyan(event.pathname)}`,
+          event.error,
+        );
+        break;
+      default:
+        break;
+    }
+  };
+}