@ecopages/core 0.2.0-beta.23 → 0.2.0-beta.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.23",
+  "version": "0.2.0-beta.25",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.23",
+    "@ecopages/file-system": "0.2.0-beta.25",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",
@@ -26,6 +26,7 @@
     "esbuild": "^0.28.0",
     "ghtml": "^4.0.2",
     "oxc-parser": "^0.124.0",
+    "oxc-resolver": "^11.24.2",
     "rolldown": "^1.1.0",
     "ws": "^8.20.1",
     "@standard-schema/spec": "^1.1.0",
@@ -207,6 +208,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"
@@ -215,6 +220,14 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/alias-resolver-plugin": {
+      "types": "./src/plugins/alias-resolver-plugin.d.ts",
+      "default": "./src/plugins/alias-resolver-plugin.js"
+    },
+    "./plugins/tsconfig-import-resolver": {
+      "types": "./src/plugins/tsconfig-import-resolver.d.ts",
+      "default": "./src/plugins/tsconfig-import-resolver.js"
+    },
     "./plugins/jsx-import-source.utils": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.js"
@@ -416,6 +429,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"
@@ -424,6 +441,14 @@
       "types": "./src/plugins/foreign-jsx-override-plugin.d.ts",
       "default": "./src/plugins/foreign-jsx-override-plugin.js"
     },
+    "./plugins/alias-resolver-plugin.ts": {
+      "types": "./src/plugins/alias-resolver-plugin.d.ts",
+      "default": "./src/plugins/alias-resolver-plugin.js"
+    },
+    "./plugins/tsconfig-import-resolver.ts": {
+      "types": "./src/plugins/tsconfig-import-resolver.d.ts",
+      "default": "./src/plugins/tsconfig-import-resolver.js"
+    },
     "./plugins/jsx-import-source.utils.ts": {
       "types": "./src/plugins/jsx-import-source.utils.d.ts",
       "default": "./src/plugins/jsx-import-source.utils.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.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";
@@ -71,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,
@@ -80,6 +83,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
       pageModuleAdapter: this.createRouteRegistryPageModuleAdapter()
     });
     await this.router.init();
+    startupTrace.markPhaseEnd("route-registry");
   }
   createRouteRegistryPageModuleAdapter() {
     this.ensureRouteRendererFactory();
@@ -428,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/build-adapter.js

@@ -120,16 +120,16 @@ import {
   setupAppRuntimePlugins
 } from "./app-build-manifest-runtime.js";
 function getAppServerBuildPlugins(appConfig) {
-  const srcDir = appConfig.absolutePaths?.srcDir;
-  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  const projectDir = appConfig.absolutePaths?.projectDir;
+  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
   return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
 }
 function getAppBrowserBuildPlugins(appConfig) {
   const manifest = getAppBuildManifest(appConfig);
   const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
   const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
-  const srcDir = appConfig.absolutePaths?.srcDir;
-  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  const projectDir = appConfig.absolutePaths?.projectDir;
+  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
   return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
 function build(options, executor = defaultRolldownBuildAdapter) {

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/build/rolldown-adapter-helpers.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { isBarePackageImportSpecifier } from "../plugins/tsconfig-import-resolver.js";
 import { collectBrowserRuntimeImportRewriteMap, rewriteBrowserRuntimeImports } from "./browser-runtime-plugin.js";
 import { createServerSideCssShimPlugin } from "./server-side-css-shim-plugin.js";
 import { createRolldownPluginBridge } from "./rolldown-plugin-bridge.js";
@@ -48,8 +49,8 @@ function transpileProfileToOptions(profile) {
       };
   }
 }
-function isPackageImport(id) {
-  return !id.startsWith(".") && !path.isAbsolute(id) && !id.startsWith("/") && !id.startsWith("node:") && !id.startsWith("@/") && !id.startsWith("~/") && !id.startsWith("#") && !id.includes(":");
+function isPackageImport(id, contextRoot) {
+  return isBarePackageImportSpecifier(id, contextRoot);
 }
 function tryResolveModule(id, resolver) {
   try {
@@ -92,7 +93,7 @@ function createExternalMatcher(options, appRootRequireCache) {
     if (explicitExternals.has(id)) {
       return true;
     }
-    if (!externalPackages || !isPackageImport(id)) {
+    if (!externalPackages || !isPackageImport(id, contextRoot)) {
       return false;
     }
     return !shouldBundlePackageImport(id, contextRoot, appRootRequireCache);

package/src/build/runtime-build-output-normalizer.js

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { isBarePackageImportSpecifier } from "../plugins/tsconfig-import-resolver.js";
 const corePackageRequire = createRequire(new URL("../../package.json", import.meta.url));
 const appDeclaredPackageCache = /* @__PURE__ */ new Map();
 const appWorkspacePackageCache = /* @__PURE__ */ new Map();
@@ -13,9 +14,6 @@ function tryResolveRuntimeImport(specifier, resolver) {
     return void 0;
   }
 }
-function isBareRuntimeImport(specifier) {
-  return !specifier.startsWith(".") && !path.isAbsolute(specifier) && !specifier.startsWith("/") && !specifier.startsWith("node:") && !specifier.startsWith("@/") && !specifier.startsWith("~/") && !specifier.startsWith("#") && !specifier.includes(":");
-}
 function extractPackageNameFromFileUrl(specifier) {
   if (!specifier.startsWith("file://")) {
     return void 0;
@@ -108,7 +106,7 @@ function isDeclaredInResolutionChain(specifier, rootDir) {
   return isDeclaredAppPackageImport(specifier, rootDir);
 }
 function rewriteRuntimeImportSpecifier(specifier, quote, rootDir) {
-  if (!isBareRuntimeImport(specifier)) {
+  if (!isBarePackageImportSpecifier(specifier, rootDir)) {
     return void 0;
   }
   if (isDeclaredInResolutionChain(specifier, rootDir)) {

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/eco/eco.types.d.ts

@@ -72,7 +72,18 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
     render: (props: P) => E | Promise<E>;
 }
 export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
-export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E> & {
+    /**
+     * Marks this layout as mounting shared client runtime state such as React context
+     * providers or query clients.
+     *
+     * @remarks
+     * When any layout in the app sets this flag, only flagged layouts participate in
+     * React auto-vendoring discovery. This keeps shell-only layouts out of provider
+     * scans while persisted SPA navigation stays on one shared vendor instance.
+     */
+    runtimeProvider?: boolean;
+};
 /**
  * Base options shared by all page variants
  */