@ecopages/core 0.2.0-beta.22 → 0.2.0-beta.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.22",
+  "version": "0.2.0-beta.24",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.22",
+    "@ecopages/file-system": "0.2.0-beta.24",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -27,7 +27,9 @@
     "ghtml": "^4.0.2",
     "oxc-parser": "^0.124.0",
     "rolldown": "^1.1.0",
-    "ws": "^8.20.1"
+    "ws": "^8.20.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@standard-schema/utils": "^0.3.0"
   },
   "exports": {
     ".": {
@@ -205,6 +207,10 @@
       "types": "./src/build/jsx-ownership-plugins.d.ts",
       "default": "./src/build/jsx-ownership-plugins.js"
     },
+    "./build/lit-static-render-worker-context": {
+      "types": "./src/build/lit-static-render-worker-context.d.ts",
+      "default": "./src/build/lit-static-render-worker-context.js"
+    },
     "./cache": {
       "types": "./src/cache/index.d.ts",
       "default": "./src/cache/index.js"
@@ -414,6 +420,10 @@
       "types": "./src/build/jsx-ownership-plugins.d.ts",
       "default": "./src/build/jsx-ownership-plugins.js"
     },
+    "./build/lit-static-render-worker-context.ts": {
+      "types": "./src/build/lit-static-render-worker-context.d.ts",
+      "default": "./src/build/lit-static-render-worker-context.js"
+    },
     "./cache.ts": {
       "types": "./src/cache/index.d.ts",
       "default": "./src/cache/index.js"

package/src/adapters/abstract/application-adapter.js

@@ -10,6 +10,7 @@ import {
   formatRuntimeServerStartedMessage
 } from "../../dev/runtime-server-started-message.js";
 import { parseCliArgs } from "../../utils/parse-cli-args.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
 class AbstractApplicationAdapter {
   appConfig;
   serverOptions;
@@ -42,6 +43,7 @@ class AbstractApplicationAdapter {
       setAppHostModuleLoader(this.appConfig, hostModuleLoader);
     }
     getAppModuleLoader(this.appConfig);
+    startupTrace.markConfigReady();
     if (options.clearOutput) {
       this.clearDistFolder().catch((error) => {
         appLogger.error("Error clearing dist folder", error);
@@ -221,6 +223,7 @@ class AbstractApplicationAdapter {
   }
   notifyListening(origin) {
     const normalizedOrigin = origin.replace(/\/$/, "");
+    startupTrace.markServerListening();
     if (!this.onAppStartCallback) {
       this.logServerStarted(normalizedOrigin);
     }

package/src/adapters/bun/create-app.js

@@ -1,6 +1,7 @@
 import { appLogger } from "../../global/app-logger.js";
 import { SharedApplicationAdapter } from "../shared/application-adapter.js";
 import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime-app-bootstrap.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
 import { createBunServerAdapter } from "./server-adapter.js";
 import { BunRuntimeHost } from "./runtime-host.js";
 import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
@@ -101,6 +102,7 @@ class BunEcopagesApp extends SharedApplicationAdapter {
     const enableHmr = dev || !preview && !build;
     const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
     const runtimeServerOptions = serverOptions;
+    startupTrace.beginServerListen();
     this.server = await this.runtimeHost.start({
       serveOptions: runtimeServerOptions,
       handleRequest: async () => new Response(null, { status: 500 }),

package/src/adapters/node/create-app.js

@@ -5,6 +5,7 @@ import { createNodeServerAdapter } from "./server-adapter.js";
 import { NodeHttpRequestBridge } from "./http-request-bridge.js";
 import { NodeRuntimeHost } from "./runtime-host.js";
 import { hostOwnsDevClient } from "../../dev/dev-client-ownership.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
 class NodeEcopagesApp extends SharedApplicationAdapter {
   serverAdapter;
   server = null;
@@ -87,6 +88,7 @@ class NodeEcopagesApp extends SharedApplicationAdapter {
       return;
     }
     const serveOptions = this.serverAdapter.getServerOptions();
+    startupTrace.beginServerListen();
     this.server = await this.runtimeHost.start({
       serveOptions,
       handleRequest: async (request) => await this.serverAdapter.handleRequest(request),

package/src/adapters/shared/server-adapter.d.ts

@@ -27,6 +27,7 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
         staticRoutes: StaticRoute[];
         hmrManager?: any;
     }): Promise<void>;
+    private ensureRouteRendererFactory;
     protected createSharedWatchRefreshCallback(options: {
         staticRoutes: StaticRoute[];
         hmrManager?: any;

package/src/adapters/shared/server-adapter.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import { AbstractServerAdapter } from "../abstract/server-adapter.js";
 import { RouteRendererFactory } from "../../route-renderer/route-renderer.js";
 import { RouteRegistry } from "../../router/server/route-registry.js";
+import { startupTrace } from "../../diagnostics/startup-trace.js";
+import { requestBuildDedupe } from "../../diagnostics/request-build-dedupe.js";
 import { MemoryCacheStore } from "../../services/cache/memory-cache-store.js";
 import { PageCacheService } from "../../services/cache/page-cache-service.js";
 import { SchemaValidationService } from "../../services/validation/schema-validation-service.js";
@@ -29,9 +31,20 @@ class SharedServerAdapter extends AbstractServerAdapter {
   schemaValidator = new SchemaValidationService();
   hostOwnsDevClient = false;
   async initializeSharedRouteHandling(options) {
+    this.ensureRouteRendererFactory();
     await this.initSharedRouter();
     this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
   }
+  ensureRouteRendererFactory() {
+    if (this.routeRendererFactory) {
+      return;
+    }
+    this.routeRendererFactory = new RouteRendererFactory({
+      appConfig: this.appConfig,
+      rendererModules: this.appConfig.runtime?.rendererModuleContext,
+      runtimeOrigin: this.runtimeOrigin
+    });
+  }
   createSharedWatchRefreshCallback(options) {
     return async () => {
       try {
@@ -60,6 +73,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
    * Web Requests (`Request`) to their corresponding internal execution paths.
    */
   async initSharedRouter() {
+    startupTrace.markPhaseStart("route-registry");
     this.router = new RouteRegistry({
       pagesDir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
       appConfig: this.appConfig,
@@ -69,18 +83,13 @@ class SharedServerAdapter extends AbstractServerAdapter {
       pageModuleAdapter: this.createRouteRegistryPageModuleAdapter()
     });
     await this.router.init();
+    startupTrace.markPhaseEnd("route-registry");
   }
   createRouteRegistryPageModuleAdapter() {
-    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.ensureRouteRendererFactory();
     return {
       loadPageModule: async (filePath) => {
-        const module = await serverModuleTranspiler.importModule({
-          filePath,
-          outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-route-modules"),
-          externalPackages: true,
-          transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
-          noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`
-        });
+        const module = await this.routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
         const page = module.default;
         return {
           staticPaths: page?.staticPaths ?? module.getStaticPaths,
@@ -104,11 +113,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
    * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
    */
   configureSharedResponseHandlers(staticRoutes, hmrManager) {
-    this.routeRendererFactory = new RouteRendererFactory({
-      appConfig: this.appConfig,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext,
-      runtimeOrigin: this.runtimeOrigin
-    });
+    this.ensureRouteRendererFactory();
     const { fileSystemResponseMatcher, explicitStaticRouteMatcher } = this.createSharedResponseHandlerDependencies(staticRoutes);
     this.fileSystemResponseMatcher = fileSystemResponseMatcher;
     this.routeHandler = new ServerRouteHandler({
@@ -427,15 +432,19 @@ class SharedServerAdapter extends AbstractServerAdapter {
    * native HTTP objects into Web Standard Requests.
    */
   async handleSharedRequest(request, context) {
-    const hmrResponse = this.tryHandleSharedHmrRequest(request, context);
-    if (hmrResponse) {
-      return hmrResponse;
-    }
-    const apiResponse = await this.tryHandleSharedApiRequest(request, context);
-    if (apiResponse) {
-      return apiResponse;
-    }
-    return this.routeHandler.handleResponse(request);
+    return requestBuildDedupe.run(
+      () => startupTrace.traceFirstRequest(request, async () => {
+        const hmrResponse = this.tryHandleSharedHmrRequest(request, context);
+        if (hmrResponse) {
+          return hmrResponse;
+        }
+        const apiResponse = await this.tryHandleSharedApiRequest(request, context);
+        if (apiResponse) {
+          return apiResponse;
+        }
+        return this.routeHandler.handleResponse(request);
+      })
+    );
   }
 }
 export {

package/src/build/app-build-manifest-runtime.js

@@ -1,5 +1,7 @@
 import { mergeBrowserRuntimeManifests } from "./browser-runtime-manifest.js";
 import { appLogger } from "../global/app-logger.js";
+import { startupTrace } from "../diagnostics/startup-trace.js";
+import { isLitStaticRenderWorkerThread } from "./lit-static-render-worker-context.js";
 function patchAppRuntime(appConfig, patch) {
   appConfig.runtime = {
     ...appConfig.runtime ?? {},
@@ -50,18 +52,26 @@ async function collectConfiguredAppBuildManifestContributions(appConfig) {
   };
 }
 async function setupAppRuntimePlugins(options) {
+  startupTrace.markPhaseStart("setupAppRuntimePlugins");
   if (options.appConfig.runtime?.runtimeAssetsPrepared) {
     appLogger.debug("Skipped setupAppRuntimePlugins: runtime assets already prepared");
     registerRuntimePlugins(options.appConfig, options.onRuntimePlugin);
+    startupTrace.markPhaseEnd("setupAppRuntimePlugins");
     return;
   }
+  if (isLitStaticRenderWorkerThread()) {
+    appLogger.debug("Lit static-render worker: skipping processor setup (main thread already prepared artifacts)");
+  }
   appLogger.debugTime("setupAppRuntimePlugins");
   try {
     for (const loader of options.appConfig.loaders.values()) {
       options.onRuntimePlugin?.(loader);
     }
+    const skipProcessorSetup = isLitStaticRenderWorkerThread();
     for (const processor of options.appConfig.processors.values()) {
-      await processor.setup();
+      if (!skipProcessorSetup) {
+        await processor.setup();
+      }
       if (processor.plugins) {
         for (const plugin of processor.plugins) {
           options.onRuntimePlugin?.(plugin);
@@ -79,6 +89,7 @@ async function setupAppRuntimePlugins(options) {
     patchAppRuntime(options.appConfig, { runtimeAssetsPrepared: true });
   } finally {
     appLogger.debugTimeEnd("setupAppRuntimePlugins");
+    startupTrace.markPhaseEnd("setupAppRuntimePlugins");
   }
 }
 export {

package/src/build/dev-browser-script-cache.d.ts

@@ -0,0 +1,34 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+export declare const DEV_BROWSER_SCRIPT_CACHE_DIR = ".browser-script-bundles";
+export declare const DEV_BROWSER_SCRIPT_CACHE_FILENAME = ".build-cache.json";
+/** Output path restored from the dev disk cache before dependency metadata is merged. */
+export type DevBrowserScriptCacheHit = {
+    filepath: string;
+};
+/**
+ * @remarks
+ * Dev asset caching spans three scopes that should not be conflated:
+ * - request dedupe (`request-build-dedupe.ts`) — one in-flight build per request key
+ * - in-memory service cache (`AssetProcessingService`) — per-process reuse within one dev server
+ * - this disk manifest (`.eco/.browser-script-bundles`) — cross-request reuse of content-script bundles
+ *
+ * Disk entries intentionally store only output file paths. Declarative fields such as
+ * `groupedBundle`, `attributes`, and `packageRole` live on the originating
+ * `ContentScriptAsset` and are merged via `materializeContentScriptAsset()` on lookup.
+ */
+export interface DevBrowserScriptCacheEntry {
+    filepath: string;
+    builtAt: number;
+}
+export interface DevBrowserScriptCacheManifest {
+    invalidationVersion: string;
+    buildInputsFingerprint: string;
+    entries: Record<string, DevBrowserScriptCacheEntry>;
+}
+/** Returns whether dev-only cross-request content-script bundle cache is active. */
+export declare function shouldUseDevBrowserScriptCache(): boolean;
+/** Looks up one persisted dev content-script output path by dependency cache key. */
+export declare function getDevBrowserScriptCacheEntry(appConfig: EcoPagesAppConfig, depKey: string): DevBrowserScriptCacheHit | null;
+/** Persists one dev content-script bundle output for cross-request reuse. */
+export declare function setDevBrowserScriptCacheEntry(appConfig: EcoPagesAppConfig, depKey: string, asset: ProcessedAsset): void;

package/src/build/dev-browser-script-cache.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppBrowserBuildPlugins } from "./build-adapter.js";
+import { createBuildInputsFingerprint, hashAppConfigFile } from "./build-input-fingerprint.js";
+import {
+  readProductionCacheManifest,
+  writeProductionCacheManifest,
+  isProductionCacheManifestCurrent,
+  matchesProductionCacheFingerprint
+} from "./production-build-cache.js";
+import { getCorePackageVersion } from "../services/module-loading/route-module-build-manifest.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import { isDevelopmentRuntime } from "../utils/runtime.js";
+const DEV_BROWSER_SCRIPT_CACHE_DIR = ".browser-script-bundles";
+const DEV_BROWSER_SCRIPT_CACHE_FILENAME = ".build-cache.json";
+function getDevBrowserScriptCacheDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), DEV_BROWSER_SCRIPT_CACHE_DIR);
+}
+function getDevBrowserScriptCacheManifestPath(appConfig) {
+  return path.join(getDevBrowserScriptCacheDir(appConfig), DEV_BROWSER_SCRIPT_CACHE_FILENAME);
+}
+function createBrowserBuildKey(appConfig) {
+  try {
+    const pluginNames = getAppBrowserBuildPlugins(appConfig).map((plugin) => plugin.name).sort().join("|");
+    return pluginNames || "default";
+  } catch {
+    return "default";
+  }
+}
+function createDevBrowserScriptCacheInvalidationVersion(appConfig) {
+  return [getCorePackageVersion(), hashAppConfigFile(appConfig), createBrowserBuildKey(appConfig)].join("::");
+}
+function readManifest(appConfig) {
+  const manifest = readProductionCacheManifest(
+    getDevBrowserScriptCacheManifestPath(appConfig)
+  );
+  if (!manifest) {
+    return void 0;
+  }
+  const invalidationVersion = createDevBrowserScriptCacheInvalidationVersion(appConfig);
+  const buildInputsFingerprint = createBuildInputsFingerprint(appConfig);
+  if (!isProductionCacheManifestCurrent(manifest, invalidationVersion) || !matchesProductionCacheFingerprint(manifest, buildInputsFingerprint)) {
+    return void 0;
+  }
+  return manifest;
+}
+function writeManifest(appConfig, manifest) {
+  writeProductionCacheManifest(getDevBrowserScriptCacheManifestPath(appConfig), manifest);
+}
+function shouldUseDevBrowserScriptCache() {
+  return isDevelopmentRuntime();
+}
+function getDevBrowserScriptCacheEntry(appConfig, depKey) {
+  if (!shouldUseDevBrowserScriptCache()) {
+    return null;
+  }
+  const manifest = readManifest(appConfig);
+  const entry = manifest?.entries[depKey];
+  if (!entry?.filepath || !fileSystem.exists(entry.filepath)) {
+    return null;
+  }
+  return { filepath: entry.filepath };
+}
+function setDevBrowserScriptCacheEntry(appConfig, depKey, asset) {
+  if (!shouldUseDevBrowserScriptCache() || !asset.filepath) {
+    return;
+  }
+  const invalidationVersion = createDevBrowserScriptCacheInvalidationVersion(appConfig);
+  const buildInputsFingerprint = createBuildInputsFingerprint(appConfig);
+  const existing = readManifest(appConfig);
+  const manifest = existing ?? {
+    invalidationVersion,
+    buildInputsFingerprint,
+    entries: {}
+  };
+  manifest.invalidationVersion = invalidationVersion;
+  manifest.buildInputsFingerprint = buildInputsFingerprint;
+  manifest.entries[depKey] = {
+    filepath: asset.filepath,
+    builtAt: Date.now()
+  };
+  writeManifest(appConfig, manifest);
+}
+export {
+  DEV_BROWSER_SCRIPT_CACHE_DIR,
+  DEV_BROWSER_SCRIPT_CACHE_FILENAME,
+  getDevBrowserScriptCacheEntry,
+  setDevBrowserScriptCacheEntry,
+  shouldUseDevBrowserScriptCache
+};

package/src/build/lit-static-render-worker-context.d.ts

@@ -0,0 +1,2 @@
+/** Returns whether the current thread is the Lit static-render worker. */
+export declare function isLitStaticRenderWorkerThread(): boolean;

package/src/build/lit-static-render-worker-context.js

@@ -0,0 +1,6 @@
+function isLitStaticRenderWorkerThread() {
+  return process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === "true";
+}
+export {
+  isLitStaticRenderWorkerThread
+};

package/src/diagnostics/request-build-dedupe.d.ts

@@ -0,0 +1,18 @@
+import type { BuildResult } from '../build/build-adapter.js';
+/**
+ * Per-request browser build dedupe cache.
+ *
+ * @remarks
+ * `DedupingBuildExecutor` only coalesces concurrent identical builds. Asset
+ * processing can call the same logical bundle several times in one request
+ * (page graph, HMR, content scripts) after the first build settles. This cache
+ * reuses the settled result until the request scope ends.
+ */
+declare class RequestBuildDedupe {
+    private readonly storage;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    dedupeBuild(key: string, build: () => Promise<BuildResult>): Promise<BuildResult>;
+    getCachedCountForTests(): number;
+}
+export declare const requestBuildDedupe: RequestBuildDedupe;
+export {};

package/src/diagnostics/request-build-dedupe.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+class RequestBuildDedupe {
+  storage = new AsyncLocalStorage();
+  run(fn) {
+    if (this.storage.getStore()) {
+      return fn();
+    }
+    return this.storage.run(/* @__PURE__ */ new Map(), fn);
+  }
+  dedupeBuild(key, build) {
+    const store = this.storage.getStore();
+    if (!store) {
+      return build();
+    }
+    const existing = store.get(key);
+    if (existing) {
+      return existing;
+    }
+    const buildPromise = build().catch((error) => {
+      store.delete(key);
+      throw error;
+    });
+    store.set(key, buildPromise);
+    return buildPromise;
+  }
+  getCachedCountForTests() {
+    return this.storage.getStore()?.size ?? 0;
+  }
+}
+const requestBuildDedupe = new RequestBuildDedupe();
+export {
+  requestBuildDedupe
+};

package/src/diagnostics/startup-trace.d.ts

@@ -0,0 +1,25 @@
+export type StartupTracePhase = 'config-ready' | 'setupAppRuntimePlugins' | 'route-registry' | 'server-listen' | 'first-request-ssr';
+declare class StartupTrace {
+    private readonly phaseStarts;
+    private readonly phases;
+    private firstRequestPending;
+    private firstRequestPath;
+    private firstRequestBundleCount;
+    private firstRequestClientBytes;
+    private summaryEmitted;
+    isEnabled(): boolean;
+    markPhaseStart(phase: StartupTracePhase): void;
+    markPhaseEnd(phase: StartupTracePhase): void;
+    markConfigReady(): void;
+    markServerListening(): void;
+    beginServerListen(): void;
+    recordBrowserBundle(outputs: Array<{
+        path: string;
+    }>): void;
+    traceFirstRequest<T>(request: Request, handler: () => Promise<T>): Promise<T>;
+    private emitFirstRequestSummary;
+    /** Resets mutable trace state for unit tests. */
+    resetForTests(): void;
+}
+export declare const startupTrace: StartupTrace;
+export {};

package/src/diagnostics/startup-trace.js

@@ -0,0 +1,121 @@
+import { statSync } from "node:fs";
+import { fileSystem } from "@ecopages/file-system";
+const LOG_PREFIX = "[ecopages:startup-trace]";
+function isStartupTraceEnabled() {
+  return process.env.ECOPAGES_STARTUP_TRACE === "true" || process.env.ECOPAGES_LOGGER_DEBUG === "true";
+}
+function wallMsSinceProcessStart() {
+  return Math.round(process.uptime() * 1e3);
+}
+function writeTraceLine(message) {
+  process.stderr.write(`${LOG_PREFIX} ${message}
+`);
+}
+class StartupTrace {
+  phaseStarts = /* @__PURE__ */ new Map();
+  phases = /* @__PURE__ */ new Map();
+  firstRequestPending = true;
+  firstRequestPath;
+  firstRequestBundleCount = 0;
+  firstRequestClientBytes = 0;
+  summaryEmitted = false;
+  isEnabled() {
+    return isStartupTraceEnabled();
+  }
+  markPhaseStart(phase) {
+    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+      return;
+    }
+    this.phaseStarts.set(phase, performance.now());
+  }
+  markPhaseEnd(phase) {
+    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+      return;
+    }
+    const startedAt = this.phaseStarts.get(phase);
+    if (startedAt === void 0) {
+      return;
+    }
+    const durationMs = Math.round(performance.now() - startedAt);
+    const record = {
+      durationMs,
+      wallMs: wallMsSinceProcessStart()
+    };
+    this.phases.set(phase, record);
+    writeTraceLine(`phase=${phase} durationMs=${durationMs} wallMs=${record.wallMs}`);
+  }
+  markConfigReady() {
+    if (!isStartupTraceEnabled() || this.phases.has("config-ready")) {
+      return;
+    }
+    const record = {
+      durationMs: 0,
+      wallMs: wallMsSinceProcessStart()
+    };
+    this.phases.set("config-ready", record);
+    writeTraceLine(`phase=config-ready wallMs=${record.wallMs}`);
+  }
+  markServerListening() {
+    this.markPhaseEnd("server-listen");
+  }
+  beginServerListen() {
+    this.markPhaseStart("server-listen");
+  }
+  recordBrowserBundle(outputs) {
+    if (!isStartupTraceEnabled() || !this.firstRequestPending) {
+      return;
+    }
+    this.firstRequestBundleCount += 1;
+    for (const output of outputs) {
+      try {
+        if (fileSystem.exists(output.path)) {
+          this.firstRequestClientBytes += statSync(output.path).size;
+        }
+      } catch {
+      }
+    }
+  }
+  async traceFirstRequest(request, handler) {
+    if (!isStartupTraceEnabled() || !this.firstRequestPending) {
+      return handler();
+    }
+    this.firstRequestPath = new URL(request.url).pathname;
+    this.markPhaseStart("first-request-ssr");
+    try {
+      return await handler();
+    } finally {
+      this.markPhaseEnd("first-request-ssr");
+      this.emitFirstRequestSummary();
+      this.firstRequestPending = false;
+    }
+  }
+  emitFirstRequestSummary() {
+    if (!isStartupTraceEnabled() || this.summaryEmitted) {
+      return;
+    }
+    this.summaryEmitted = true;
+    writeTraceLine(
+      [
+        "summary",
+        `path=${this.firstRequestPath ?? "unknown"}`,
+        `bundleCount=${this.firstRequestBundleCount}`,
+        `clientBundleBytes=${this.firstRequestClientBytes}`,
+        `wallMs=${wallMsSinceProcessStart()}`
+      ].join(" ")
+    );
+  }
+  /** Resets mutable trace state for unit tests. */
+  resetForTests() {
+    this.phaseStarts.clear();
+    this.phases.clear();
+    this.firstRequestPending = true;
+    this.firstRequestPath = void 0;
+    this.firstRequestBundleCount = 0;
+    this.firstRequestClientBytes = 0;
+    this.summaryEmitted = false;
+  }
+}
+const startupTrace = new StartupTrace();
+export {
+  startupTrace
+};

package/src/env.d.ts

@@ -3,6 +3,8 @@ interface EcopagesEnv {
 	ECOPAGES_HOSTNAME: string;
 	ECOPAGES_PORT: string;
 	ECOPAGES_LOGGER_DEBUG: 'true' | 'false';
+	/** When `true`, emits startup phase timings to stderr. Also enabled when `ECOPAGES_LOGGER_DEBUG=true`. */
+	ECOPAGES_STARTUP_TRACE?: 'true' | 'false';
 }
 
 declare global {

package/src/index.d.ts

@@ -4,3 +4,4 @@ export { eco } from './eco/eco.js';
 export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';
 export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
 export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';
+export { SchemaError, validateStandardSchema } from './services/validation/validate-standard-schema.js';

package/src/index.js

@@ -8,7 +8,9 @@ import {
   normalizeTransformId
 } from "./plugins/source-transform.js";
 import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
+import { SchemaError, validateStandardSchema } from "./services/validation/validate-standard-schema.js";
 export {
+  SchemaError,
   createEcoBuildPluginFromSourceTransform,
   createEcoComponentMetaTransform,
   createVitePluginFromSourceTransform,
@@ -17,5 +19,6 @@ export {
   defineGroupHandler,
   eco,
   getAppSourceTransforms,
-  normalizeTransformId
+  normalizeTransformId,
+  validateStandardSchema
 };

package/src/plugins/integration-plugin.d.ts

@@ -197,6 +197,14 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     initializeRenderer(options?: {
         rendererModules?: unknown;
     }): IntegrationRenderer<C>;
+    /**
+     * Shapes one dependency batch before core asset processing runs.
+     *
+     * @remarks
+     * Integrations use this to assign grouped-build metadata or other batch-level
+     * policy without teaching core about integration-specific asset graphs.
+     */
+    prepareAssetDependencies?(dependencies: AssetDefinition[]): AssetDefinition[];
     /**
      * Prepares build-facing contributions before the app build manifest is sealed.
      *

package/src/plugins/processor.d.ts

@@ -1,5 +1,6 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.js';
+import { GENERATED_BASE_PATHS } from '../config/constants.js';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
@@ -7,6 +8,11 @@ export declare const PROCESSOR_ERRORS: {
     readonly CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context";
 };
 export declare function mergeProcessorOptions<TDefaults, TOverrides>(defaults: TDefaults, overrides: TOverrides): TDefaults & TOverrides;
+export declare function resolveGeneratedPath(type: keyof typeof GENERATED_BASE_PATHS, options: {
+    root: string;
+    module: string;
+    subPath?: string;
+}): string;
 export interface ProcessorWatchContext {
     path: string;
     bridge: IClientBridge;