evolit 0.1.0-alpha.17 → 0.1.0-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

package/src/build.js

@@ -255,17 +255,35 @@ export async function buildProject(projectRoot) {
         ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
       ].join("\n");
     },
-    resolveBootstrap({ result }) {
+    resolveBootstrap({ routeResult, result }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        clientAssets,
+      );
       return createHydrationBootstrap({
-        hydrationData: normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        hydrationData: normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
         assetResolver,
         hydrationModuleUrl,
       });
     },
-    transformDocument({ result, document }) {
+    transformDocument({ routeResult, result, document }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        clientAssets,
+      );
       return rewriteHydrationDataScript(
         document,
-        normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
       );
     },
   });

package/src/cli.js

@@ -3,7 +3,9 @@
 import path from "node:path";
 import process from "node:process";
 import { scaffoldSite } from "./scaffold.js";
-import { terminal } from "./terminal.js";
+import { createDevelopmentEventReporter } from "./development-events.js";
+
+const reportEvent = createDevelopmentEventReporter();
 
 function parseArguments(argv) {
   const [command, ...rest] = argv;
@@ -25,9 +27,7 @@ function parseArguments(argv) {
 }
 
 function printUsage() {
-  console.log(`${terminal.bold("Usage:")} evolit <directory>`);
-  console.log(`       evolit ${terminal.cyan("init")} <directory>`);
-  console.log(`       evolit ${terminal.cyan("<dev|build|start>")} [--port 3000]`);
+  reportEvent({ type: "usage" });
 }
 
 async function createSite(projectRoot, targetDirectory) {
@@ -36,7 +36,7 @@ async function createSite(projectRoot, targetDirectory) {
   }
 
   const createdDirectory = await scaffoldSite(path.resolve(projectRoot, targetDirectory));
-  console.log(`${terminal.green("✓")} Created evolit site: ${terminal.cyan(createdDirectory)}`);
+  reportEvent({ type: "site-created", directory: createdDirectory });
 }
 
 async function run() {
@@ -56,25 +56,29 @@ async function run() {
   if (command === "build") {
     const { buildProject } = await import("./build.js");
     const manifestPath = await buildProject(projectRoot);
-    console.log(`${terminal.green("✓")} Built Evolit app: ${terminal.cyan(path.relative(projectRoot, manifestPath))}`);
+    reportEvent({
+      type: "build-ready",
+      manifestPath: path.relative(projectRoot, manifestPath),
+    });
     return;
   }
 
   if (command === "start") {
     const { createStartServer } = await import("./server.js");
-    console.log(`${terminal.cyan("▲")} ${terminal.bold("Evolit")} ${terminal.cyan("start")}`);
+    reportEvent({ type: "server-starting", mode: "start" });
     const server = await createStartServer(projectRoot, options);
     await server.listen();
-    console.log(`${terminal.green("✓")} Ready on ${terminal.cyan(`http://localhost:${server.port}`)}`);
+    reportEvent({ type: "server-ready", port: server.port });
     return;
   }
 
   if (command === "dev") {
     const { createDevServer } = await import("./server.js");
-    console.log(`${terminal.cyan("▲")} ${terminal.bold("Evolit")} ${terminal.cyan("dev")}`);
-    const server = await createDevServer(projectRoot, options);
+    const server = await createDevServer(projectRoot, {
+      ...options,
+      onDevelopmentEvent: reportEvent,
+    });
     await server.listen();
-    console.log(`${terminal.green("✓")} Ready on ${terminal.cyan(`http://localhost:${server.port}`)}`);
     return;
   }
 
@@ -82,8 +86,6 @@ async function run() {
 }
 
 run().catch((error) => {
-  console.error(
-    `${terminal.red("[evolit]")} ${terminal.red("✖")} ${error instanceof Error ? error.stack ?? error.message : String(error)}`,
-  );
+  reportEvent({ type: "fatal-error", error });
   process.exitCode = 1;
 });

package/src/client-assets.js

@@ -923,10 +923,25 @@ export function getClientOutputRoot(projectRoot, mode) {
 }
 
 export function toClientModuleRelativePath(projectRoot, sourcePath) {
-  const relativePath = path.relative(projectRoot, sourcePath);
+  const relativePath = toClientSourceRelativePath(projectRoot, sourcePath);
   return toCompiledClientModuleRelativePath(relativePath);
 }
 
+function toClientSourceRelativePath(projectRoot, sourcePath) {
+  const relativePath = path.relative(projectRoot, sourcePath);
+  const isOutsideProject = relativePath === ".."
+    || relativePath.startsWith(`..${path.sep}`)
+    || path.isAbsolute(relativePath);
+  if (!isOutsideProject) {
+    return relativePath;
+  }
+
+  return path.join(
+    "__unmanaged__",
+    ...relativePath.split(path.sep).map((segment) => segment === ".." ? "__up__" : segment),
+  );
+}
+
 function toCompiledClientModuleRelativePath(relativePath) {
   const extension = path.extname(relativePath);
   return extension
@@ -934,17 +949,66 @@ function toCompiledClientModuleRelativePath(relativePath) {
     : `${relativePath}.mjs`;
 }
 
+function toCatchAllClientModuleRelativePath(clientModule) {
+  return clientModule
+    .split(/[\\/]/)
+    .map((segment) => {
+      if (segment.startsWith("[[...") && segment.endsWith("]]")) {
+        return `**...${segment.slice(5, -2)}**`;
+      }
+
+      if (segment.startsWith("[...") && segment.endsWith("]")) {
+        return `*...${segment.slice(4, -1)}*`;
+      }
+
+      return segment;
+    })
+    .join("/");
+}
+
+function toRollupSafeClientModuleRelativePath(clientModule) {
+  return clientModule.replaceAll(/[\[\]]/g, "_");
+}
+
+function getClientModuleCandidates(clientModule) {
+  const normalizedClientModule = clientModule.split(path.sep).join("/");
+  return [...new Set([
+    normalizedClientModule,
+    toCatchAllClientModuleRelativePath(normalizedClientModule),
+    toRollupSafeClientModuleRelativePath(normalizedClientModule),
+  ])];
+}
+
+function getClientModulePublicUrl(assetManifest, clientModule) {
+  for (const candidate of getClientModuleCandidates(clientModule)) {
+    const publicUrl = assetManifest.byClientModule[candidate];
+    if (typeof publicUrl === "string" && publicUrl.length > 0) {
+      return publicUrl;
+    }
+  }
+
+  const candidates = new Set(getClientModuleCandidates(clientModule));
+  const asset = assetManifest.assets.find((entry) =>
+    candidates.has(entry?.clientModule) && typeof entry?.publicUrl === "string",
+  );
+  if (asset) {
+    return asset.publicUrl;
+  }
+
+  return null;
+}
+
+function isVirtualClientModuleId(moduleId) {
+  return moduleId.startsWith("/app/") || moduleId.startsWith("/__unmanaged__/");
+}
+
 function toPublicHydrationModuleId(projectRoot, moduleId) {
   if (typeof moduleId !== "string" || moduleId.length === 0) {
     return null;
   }
 
   if (path.isAbsolute(moduleId)) {
-    if (!moduleId.startsWith(projectRoot)) {
-      return null;
-    }
-
-    const relativePath = path.relative(projectRoot, moduleId).split(path.sep).join("/");
+    const relativePath = toClientSourceRelativePath(projectRoot, moduleId).split(path.sep).join("/");
     return `/${relativePath}`;
   }
 
@@ -986,14 +1050,10 @@ export function createAssetResolver(projectRoot, options = {}) {
     }
 
     let relativeClientModule = null;
-    if (moduleId.startsWith("/") && !moduleId.startsWith(projectRoot)) {
-      relativeClientModule = toCompiledClientModuleRelativePath(moduleId.slice(1));
-    } else if (path.isAbsolute(moduleId)) {
-      if (!moduleId.startsWith(projectRoot)) {
-        return null;
-      }
-
+    if (path.isAbsolute(moduleId) && !isVirtualClientModuleId(moduleId)) {
       relativeClientModule = toClientModuleRelativePath(projectRoot, moduleId);
+    } else if (moduleId.startsWith("/")) {
+      relativeClientModule = toCompiledClientModuleRelativePath(moduleId.slice(1));
     }
 
     if (!relativeClientModule) {
@@ -1001,10 +1061,7 @@ export function createAssetResolver(projectRoot, options = {}) {
     }
 
     if (assetManifest) {
-      return getAssetByClientModule(
-        assetManifest,
-        relativeClientModule,
-      )?.publicUrl ?? null;
+      return getClientModulePublicUrl(assetManifest, relativeClientModule);
     }
 
     return null;
@@ -1029,8 +1086,8 @@ export function createHydrationBootstrap({
   hydrationModuleUrl = "@litsx/ssr/hydration",
 }) {
   const normalizedHydrationData = normalizeHydrationDataForClient(hydrationData);
-  const moduleUrls = [...new Set(
-    (normalizedHydrationData?.roots ?? [])
+  const rootModuleUrls = [...new Set([
+    ...(normalizedHydrationData?.roots ?? [])
       .map((root) => {
         if (typeof root?.moduleId !== "string" || root.moduleId.length === 0) {
           return null;
@@ -1039,13 +1096,18 @@ export function createHydrationBootstrap({
         return assetResolver?.(root.moduleId) ?? null;
       })
       .filter((moduleUrl) => typeof moduleUrl === "string" && moduleUrl.length > 0),
+  ])];
+  const clientImports = [...new Set(
+    (Array.isArray(normalizedHydrationData?.clientImports)
+      ? normalizedHydrationData.clientImports
+      : []).filter((moduleUrl) => typeof moduleUrl === "string" && moduleUrl.length > 0),
   )];
 
-  if (moduleUrls.length === 0) {
+  if (rootModuleUrls.length === 0 && clientImports.length === 0) {
     return "";
   }
 
-  const moduleLoaders = moduleUrls
+  const moduleLoaders = rootModuleUrls
     .map((moduleUrl) => `  () => import(${JSON.stringify(moduleUrl)})`)
     .join(",\n");
 
@@ -1053,7 +1115,7 @@ export function createHydrationBootstrap({
 import { hydratePage, registerHydrationModules } from ${JSON.stringify(hydrationModuleUrl)};
 
 await hydratePage({
-  clientImports: [],
+  clientImports: ${JSON.stringify(clientImports)},
   register: () => registerHydrationModules([
 ${moduleLoaders}
   ])
@@ -1063,7 +1125,11 @@ ${moduleLoaders}
   return escapeInlineScriptText(source);
 }
 
-export function normalizeHydrationDataForClient(hydrationData, projectRoot = null) {
+export function normalizeHydrationDataForClient(
+  hydrationData,
+  projectRoot = null,
+  additionalClientImports = [],
+) {
   if (!hydrationData || typeof hydrationData !== "object") {
     return hydrationData ?? null;
   }
@@ -1096,7 +1162,10 @@ export function normalizeHydrationDataForClient(hydrationData, projectRoot = nul
     roots,
   };
   const payload = hydrationData.payload;
-  const clientImports = hydrationData.clientImports;
+  const clientImports = [...new Set([
+    ...(Array.isArray(hydrationData.clientImports) ? hydrationData.clientImports : []),
+    ...(Array.isArray(additionalClientImports) ? additionalClientImports : []),
+  ].filter((value) => typeof value === "string" && value.length > 0))];
 
   Object.defineProperties(normalizedHydrationData, {
     payload: {
@@ -1728,9 +1797,14 @@ async function bundleClientAssets(projectRoot, options = {}) {
 
         const outputPath = path.join(staticRoot, chunk.fileName);
         const publicUrl = toStaticPublicUrl(chunk.fileName);
-        const isNamedEntry = chunk.isEntry && clientModuleByEntryName.has(chunk.name);
+        const entryClientModule = clientModuleByEntryName.get(chunk.name)
+          ?? [...clientModuleByEntryName.entries()].find(([entryName]) =>
+            toRollupSafeClientModuleRelativePath(entryName) === chunk.name,
+          )?.[1]
+          ?? null;
+        const isNamedEntry = chunk.isEntry && entryClientModule != null;
         const clientModule = isNamedEntry
-          ? clientModuleByEntryName.get(chunk.name)
+          ? entryClientModule
           : chunk.fileName;
         const transitiveMetadata = isNamedEntry
           ? await collectTransitiveClientModuleMetadata(projectRoot, mode, clientModule)
@@ -1939,7 +2013,7 @@ export function resolveRouteClientImports(routeResult, projectRoot, assetManifes
     const clientModule = extension
       ? `${relativePath.slice(0, -extension.length)}.mjs`
       : `${relativePath}.mjs`;
-    return normalizedManifest.byClientModule[clientModule] ?? null;
+    return getClientModulePublicUrl(normalizedManifest, clientModule);
   }).filter((publicUrl) => typeof publicUrl === "string"))];
 }
 

package/src/compiler.js

@@ -25,7 +25,7 @@ const developmentGraphCache = new Map();
 const developmentGraphDependencies = new Map();
 const developmentModuleNamespaceCache = new Map();
 const developmentGraphVersions = new Map();
-const developmentExternalImportWarnings = new Set();
+const developmentUnmanagedImportWarnings = new Set();
 
 function isRelativeSpecifier(specifier) {
   return specifier.startsWith("./") || specifier.startsWith("../");
@@ -70,15 +70,15 @@ function isPathOutsideProject(projectRoot, filePath) {
   );
 }
 
-function reportDevelopmentExternalImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent) {
+function reportDevelopmentUnmanagedImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent) {
   const warningKey = `${path.resolve(projectRoot)}::${sourcePath}::${resolvedImportPath}`;
-  if (developmentExternalImportWarnings.has(warningKey)) {
+  if (developmentUnmanagedImportWarnings.has(warningKey)) {
     return;
   }
 
-  developmentExternalImportWarnings.add(warningKey);
+  developmentUnmanagedImportWarnings.add(warningKey);
   onDevelopmentEvent?.({
-    type: "external-import",
+    type: "unmanaged-import",
     sourcePath,
     resolvedImportPath,
   });
@@ -159,7 +159,7 @@ function toOutputRelativePath(projectRoot, sourcePath) {
   }
 
   return path.join(
-    "__external__",
+    "__unmanaged__",
     ...relativePath.split(path.sep).map((segment) => segment === ".." ? "__up__" : segment),
   );
 }
@@ -211,7 +211,7 @@ async function rewriteRelativeSpecifiers({
     }
 
     if (mode === "development" && isPathOutsideProject(projectRoot, resolvedImportPath)) {
-      reportDevelopmentExternalImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent);
+      reportDevelopmentUnmanagedImport(projectRoot, sourcePath, resolvedImportPath, onDevelopmentEvent);
     }
 
     const importerOutputPath = toOutputPath(projectRoot, outputRoot, sourcePath);
@@ -339,9 +339,9 @@ export function invalidateDevelopmentCompilationCache(projectRoot, changedPaths
   let invalidated = false;
 
   if (normalizedChangedPaths == null) {
-    for (const warningKey of developmentExternalImportWarnings) {
+    for (const warningKey of developmentUnmanagedImportWarnings) {
       if (warningKey.startsWith(prefix)) {
-        developmentExternalImportWarnings.delete(warningKey);
+        developmentUnmanagedImportWarnings.delete(warningKey);
       }
     }
   }

package/src/deployment-runtime.js

@@ -293,19 +293,37 @@ export async function createRequestRenderer({
         ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
       ].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,
       });
     },
-    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,
+        ),
       );
     },
   });

package/src/development-events.js

@@ -0,0 +1,87 @@
+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 "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;
+    }
+  };
+}

package/src/render.js

@@ -12,7 +12,7 @@ import {
   isEvolitHttpSignal,
   runWithRequestContext,
 } from "./request-context.js";
-import { terminal } from "./terminal.js";
+import { createDevelopmentEventReporter } from "./development-events.js";
 import {
   LITSX_COMPONENT,
   LITSX_SERVER_COMPONENT,
@@ -90,10 +90,12 @@ function createBoundaryError(error, { mode, route, reportRouteError }) {
   if (typeof reportRouteError === "function") {
     reportRouteError(report);
   } else {
-    console.error(
-      `${terminal.red("[evolit]")} ${terminal.red("✖")} Route rendering failed ${terminal.dim(`(${digest})`)} at ${terminal.cyan(route.pathname)}`,
-      originalError,
-    );
+    createDevelopmentEventReporter()({
+      type: "route-error",
+      digest,
+      pathname: route.pathname,
+      error: originalError,
+    });
   }
 
   const boundaryError = new Error("An unexpected server error occurred.");

package/src/server.js

@@ -9,7 +9,7 @@ import { APP_DIRECTORY, BUILD_DIRECTORY, INTERNAL_DIRECTORY, MANIFEST_FILENAME }
 import { normalizeClientAssetManifest } from "./client-assets.js";
 import { pathExists, readJson } from "./fs-utils.js";
 import { createDefaultRouteCacheKey, resolveResponseCacheRuntime } from "./response-cache.js";
-import { terminal } from "./terminal.js";
+import { createDevelopmentEventReporter } from "./development-events.js";
 
 function getPort(explicitPort) {
   const port = explicitPort ?? process.env.PORT ?? "3000";
@@ -141,57 +141,9 @@ async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
 
 async function createServer(projectRoot, mode, explicitPort, options = {}) {
   const reportDevelopmentEvent = mode === "development"
-    ? options.onDevelopmentEvent ?? ((event) => {
-      switch (event.type) {
-        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 "invalidated":
-          console.log(
-            `${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Source change detected${event.changedPathCount == null ? "" : ` (${event.changedPathCount} files)`}; invalidated ${event.affectedClientEntryCount} client entries.`,
-          );
-          break;
-        case "external-import":
-          console.warn(
-            `${terminal.yellow("[evolit]")} ${terminal.yellow("⚠")} Development import ${terminal.cyan(JSON.stringify(event.resolvedImportPath))} from ${terminal.cyan(JSON.stringify(event.sourcePath))} is outside the project root. It will be emitted under ${terminal.cyan("/_evolit/static/__external__/")}.`,
-          );
-          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;
-        default:
-          break;
-      }
-    })
+    ? options.onDevelopmentEvent ?? createDevelopmentEventReporter()
     : null;
+  reportDevelopmentEvent?.({ type: "server-starting" });
   const evolitConfig = options.evolitConfig ?? await loadEvolitConfig(projectRoot);
   const responseCacheRuntime = options.responseCacheStore
     ? {
@@ -331,6 +283,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
       await new Promise((resolve) => {
         server.listen(port, resolve);
       });
+      reportDevelopmentEvent?.({ type: "server-ready", port });
       return server;
     },
     async close() {