@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/diagnostics/startup-trace.js

@@ -1,253 +1,281 @@
-import { mkdirSync, statSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { availableParallelism } from "node:os";
-import { fileSystem } from "@ecopages/file-system";
-const LOG_PREFIX = "[ecopages:startup-trace]";
+import { mkdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { availableParallelism } from 'node:os';
+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";
+    return process.env.ECOPAGES_STARTUP_TRACE === 'true' || process.env.ECOPAGES_LOGGER_DEBUG === 'true';
 }
 function wallMsSinceProcessStart() {
-  return Math.round(process.uptime() * 1e3);
+    return Math.round(process.uptime() * 1000);
 }
 function resolveTraceBuildParallelism() {
-  const fromEnv = process.env.ECOPAGES_DEV_BUILD_PARALLELISM ?? process.env.ECOPAGES_DEV_HMR_PARALLELISM;
-  if (fromEnv) {
-    return fromEnv;
-  }
-  return String(Math.max(1, availableParallelism()));
+    const fromEnv = process.env.ECOPAGES_DEV_BUILD_PARALLELISM ?? process.env.ECOPAGES_DEV_HMR_PARALLELISM;
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return String(Math.max(1, availableParallelism()));
 }
 function writeTraceLine(message) {
-  process.stderr.write(`${LOG_PREFIX} ${message}
-`);
+    process.stderr.write(`${LOG_PREFIX} ${message}\n`);
 }
 function resolveStartupTraceJsonPath() {
-  const configured = process.env.ECOPAGES_STARTUP_TRACE_JSON?.trim();
-  return configured && configured.length > 0 ? configured : void 0;
+    const configured = process.env.ECOPAGES_STARTUP_TRACE_JSON?.trim();
+    return configured && configured.length > 0 ? configured : undefined;
 }
 class StartupTrace {
-  phaseNesting = /* @__PURE__ */ new Map();
-  phases = /* @__PURE__ */ new Map();
-  firstRequestPending = true;
-  firstRequestPath;
-  firstRequestBundleCount = 0;
-  firstRequestClientBytes = 0;
-  firstRequestGraphBuildCount = 0;
-  summaryEmitted = false;
-  firstPageBrowserGraphEmitted = false;
-  clientRequestCount = 0;
-  clientTransferredBytes = 0;
-  hmrConnected = false;
-  hydrationReadyMs = null;
-  isEnabled() {
-    return isStartupTraceEnabled();
-  }
-  markPhaseStart(phase) {
-    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
-      return;
-    }
-    const nesting = this.phaseNesting.get(phase);
-    if (!nesting) {
-      this.phaseNesting.set(phase, { outerStart: performance.now(), depth: 1 });
-      return;
-    }
-    nesting.depth += 1;
-  }
-  markPhaseEnd(phase) {
-    if (!isStartupTraceEnabled() || this.phases.has(phase)) {
-      return;
-    }
-    const nesting = this.phaseNesting.get(phase);
-    if (!nesting) {
-      return;
-    }
-    nesting.depth -= 1;
-    if (nesting.depth > 0) {
-      return;
-    }
-    const durationMs = Math.round(performance.now() - nesting.outerStart);
-    const record = {
-      durationMs,
-      wallMs: wallMsSinceProcessStart()
-    };
-    this.phases.set(phase, record);
-    this.phaseNesting.delete(phase);
-    writeTraceLine(`phase=${phase} durationMs=${durationMs} wallMs=${record.wallMs}`);
-    this.writeJsonReport();
-  }
-  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} buildParallelism=${resolveTraceBuildParallelism()}`);
-    this.writeJsonReport();
-  }
-  markServerListening() {
-    this.markPhaseEnd("server-listen");
-  }
-  beginServerListen() {
-    this.markPhaseStart("server-listen");
-  }
-  markFirstByte() {
-    if (!isStartupTraceEnabled() || this.phases.has("first-byte")) {
-      return;
-    }
-    this.markPhaseEnd("first-byte");
-  }
-  beginFirstByte() {
-    this.markPhaseStart("first-byte");
-  }
-  markFirstPageBrowserGraphReady(graphBuildCount) {
-    if (!isStartupTraceEnabled() || this.firstPageBrowserGraphEmitted) {
-      return;
-    }
-    if (typeof graphBuildCount === "number") {
-      this.firstRequestGraphBuildCount = graphBuildCount;
-    }
-    this.firstPageBrowserGraphEmitted = true;
-    this.markPhaseEnd("first-page-browser-graph");
-  }
-  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 {
-      }
-    }
-  }
-  recordClientTransfer(requestCount, transferredBytes) {
-    if (!isStartupTraceEnabled()) {
-      return;
-    }
-    this.clientRequestCount = requestCount;
-    this.clientTransferredBytes = transferredBytes;
-    this.markPhaseEnd("client-transfer");
-  }
-  beginClientTransfer() {
-    this.markPhaseStart("client-transfer");
-  }
-  recordClientHydration(durationMs) {
-    if (!isStartupTraceEnabled()) {
-      return;
-    }
-    this.hydrationReadyMs = durationMs;
-    this.markPhaseEnd("client-hydration");
-  }
-  beginClientHydration() {
-    this.markPhaseStart("client-hydration");
-  }
-  recordHmrConnected() {
-    if (!isStartupTraceEnabled()) {
-      return;
-    }
-    this.hmrConnected = true;
-  }
-  async traceFirstRequest(request, handler) {
-    if (!isStartupTraceEnabled() || !this.firstRequestPending) {
-      return handler();
-    }
-    this.firstRequestPath = new URL(request.url).pathname;
-    this.markPhaseStart("first-page-browser-graph");
-    this.markPhaseStart("first-request-ssr");
-    try {
-      return await handler();
-    } finally {
-      this.markPhaseEnd("first-request-ssr");
-      this.emitFirstRequestSummary();
-      this.firstRequestPending = false;
-      this.writeJsonReport();
-    }
-  }
-  emitFirstRequestSummary() {
-    if (!isStartupTraceEnabled() || this.summaryEmitted) {
-      return;
-    }
-    this.summaryEmitted = true;
-    writeTraceLine(
-      [
-        "summary",
-        `path=${this.firstRequestPath ?? "unknown"}`,
-        `bundleCount=${this.firstRequestBundleCount}`,
-        `clientBundleBytes=${this.firstRequestClientBytes}`,
-        `graphBuildCount=${this.firstRequestGraphBuildCount}`,
-        `wallMs=${wallMsSinceProcessStart()}`
-      ].join(" ")
-    );
-  }
-  writeJsonReport() {
-    const outputPath = resolveStartupTraceJsonPath();
-    if (!outputPath) {
-      return;
-    }
-    const report = this.createReport();
-    mkdirSync(path.dirname(outputPath), { recursive: true });
-    writeFileSync(outputPath, JSON.stringify(report, null, 2), "utf-8");
-  }
-  createReport() {
-    const phases = {};
-    for (const [phase, record] of this.phases) {
-      phases[phase] = record;
-    }
-    return {
-      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      runtime: typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.version}`,
-      platform: process.platform,
-      phases,
-      firstRequest: this.firstRequestPath ? {
-        path: this.firstRequestPath,
-        bundleCount: this.firstRequestBundleCount,
-        clientBundleBytes: this.firstRequestClientBytes,
-        graphBuildCount: this.firstRequestGraphBuildCount,
-        wallMs: wallMsSinceProcessStart()
-      } : void 0,
-      client: this.clientRequestCount > 0 || this.hydrationReadyMs !== null ? {
-        requestCount: this.clientRequestCount,
-        transferredBytes: this.clientTransferredBytes,
-        hmrConnected: this.hmrConnected,
-        hydrationReadyMs: this.hydrationReadyMs
-      } : void 0
-    };
-  }
-  /** Resets mutable trace state for unit tests. */
-  resetForTests() {
-    this.phaseNesting.clear();
-    this.phases.clear();
-    this.firstRequestPending = true;
-    this.firstRequestPath = void 0;
-    this.firstRequestBundleCount = 0;
-    this.firstRequestClientBytes = 0;
-    this.firstRequestGraphBuildCount = 0;
-    this.summaryEmitted = false;
-    this.firstPageBrowserGraphEmitted = false;
-    this.clientRequestCount = 0;
-    this.clientTransferredBytes = 0;
-    this.hmrConnected = false;
-    this.hydrationReadyMs = null;
-  }
-  /**
-   * Resets only the first-request bundle counters.
-   *
-   * @remarks
-   * Used by tests that need to re-measure first-request browser bundle work
-   * without clearing earlier startup phase records.
-   */
-  resetFirstRequestCounters() {
-    this.firstRequestBundleCount = 0;
-    this.firstRequestClientBytes = 0;
-    this.firstRequestGraphBuildCount = 0;
-  }
+    phaseNesting = new Map();
+    phases = new Map();
+    firstRequestPending = true;
+    firstRequestPath;
+    firstRequestBundleCount = 0;
+    firstRequestClientBytes = 0;
+    firstRequestGraphBuildCount = 0;
+    firstRequestCompletedWallMs;
+    summaryEmitted = false;
+    firstPageBrowserGraphEmitted = false;
+    devClientTransformEmitted = false;
+    clientRequestCount = 0;
+    clientTransferredBytes = 0;
+    hmrConnected = false;
+    hydrationReadyMs = null;
+    isEnabled() {
+        return isStartupTraceEnabled();
+    }
+    markPhaseStart(phase) {
+        if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+            return;
+        }
+        const nesting = this.phaseNesting.get(phase);
+        if (!nesting) {
+            this.phaseNesting.set(phase, { outerStart: performance.now(), depth: 1 });
+            return;
+        }
+        nesting.depth += 1;
+    }
+    markPhaseEnd(phase) {
+        if (!isStartupTraceEnabled() || this.phases.has(phase)) {
+            return;
+        }
+        const nesting = this.phaseNesting.get(phase);
+        if (!nesting) {
+            return;
+        }
+        nesting.depth -= 1;
+        if (nesting.depth > 0) {
+            return;
+        }
+        const durationMs = Math.round(performance.now() - nesting.outerStart);
+        const record = {
+            durationMs,
+            wallMs: wallMsSinceProcessStart(),
+        };
+        this.phases.set(phase, record);
+        this.phaseNesting.delete(phase);
+        writeTraceLine(`phase=${phase} durationMs=${durationMs} wallMs=${record.wallMs}`);
+        this.writeJsonReport();
+    }
+    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} buildParallelism=${resolveTraceBuildParallelism()}`);
+        this.writeJsonReport();
+    }
+    markServerListening() {
+        this.markPhaseEnd('server-listen');
+    }
+    beginServerListen() {
+        this.markPhaseStart('server-listen');
+    }
+    markFirstByte() {
+        if (!isStartupTraceEnabled() || this.phases.has('first-byte')) {
+            return;
+        }
+        this.markPhaseEnd('first-byte');
+    }
+    beginFirstByte() {
+        this.markPhaseStart('first-byte');
+    }
+    beginDevClientTransform() {
+        if (!isStartupTraceEnabled() || this.devClientTransformEmitted) {
+            return;
+        }
+        this.markPhaseStart('dev-client-transform');
+    }
+    endDevClientTransform() {
+        if (!isStartupTraceEnabled() || this.devClientTransformEmitted) {
+            return;
+        }
+        this.devClientTransformEmitted = true;
+        this.markPhaseEnd('dev-client-transform');
+    }
+    /**
+     * Records the first Page Browser Graph completion for startup tracing.
+     *
+     * @param graphBuildCount Session graph build counter when the first Page Browser Graph finished.
+     */
+    markFirstPageBrowserGraphReady(graphBuildCount) {
+        if (!isStartupTraceEnabled() || this.firstPageBrowserGraphEmitted) {
+            return;
+        }
+        if (this.firstRequestPending && typeof graphBuildCount === 'number') {
+            this.firstRequestGraphBuildCount = graphBuildCount;
+        }
+        this.firstPageBrowserGraphEmitted = true;
+        this.markPhaseEnd('first-page-browser-graph');
+    }
+    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 {
+                // ignore unreadable outputs
+            }
+        }
+    }
+    recordClientTransfer(requestCount, transferredBytes) {
+        if (!isStartupTraceEnabled()) {
+            return;
+        }
+        this.clientRequestCount = requestCount;
+        this.clientTransferredBytes = transferredBytes;
+        this.markPhaseEnd('client-transfer');
+    }
+    beginClientTransfer() {
+        this.markPhaseStart('client-transfer');
+    }
+    recordClientHydration(durationMs) {
+        if (!isStartupTraceEnabled()) {
+            return;
+        }
+        this.hydrationReadyMs = durationMs;
+        this.markPhaseEnd('client-hydration');
+    }
+    beginClientHydration() {
+        this.markPhaseStart('client-hydration');
+    }
+    recordHmrConnected() {
+        if (!isStartupTraceEnabled()) {
+            return;
+        }
+        this.hmrConnected = true;
+    }
+    async traceFirstRequest(request, handler) {
+        if (!this.firstRequestPending) {
+            return handler();
+        }
+        this.firstRequestPath = new URL(request.url).pathname;
+        if (!isStartupTraceEnabled()) {
+            this.firstRequestPending = false;
+            return handler();
+        }
+        this.markPhaseStart('first-page-browser-graph');
+        this.markPhaseStart('first-request-ssr');
+        try {
+            return await handler();
+        }
+        finally {
+            this.markPhaseEnd('first-request-ssr');
+            this.firstRequestCompletedWallMs = wallMsSinceProcessStart();
+            this.emitFirstRequestSummary();
+            this.firstRequestPending = false;
+            this.writeJsonReport();
+        }
+    }
+    emitFirstRequestSummary() {
+        if (!isStartupTraceEnabled() || this.summaryEmitted) {
+            return;
+        }
+        this.summaryEmitted = true;
+        writeTraceLine([
+            'summary',
+            `path=${this.firstRequestPath ?? 'unknown'}`,
+            `bundleCount=${this.firstRequestBundleCount}`,
+            `clientBundleBytes=${this.firstRequestClientBytes}`,
+            `graphBuildCount=${this.firstRequestGraphBuildCount}`,
+            `wallMs=${wallMsSinceProcessStart()}`,
+        ].join(' '));
+    }
+    writeJsonReport() {
+        const outputPath = resolveStartupTraceJsonPath();
+        if (!outputPath) {
+            return;
+        }
+        const report = this.createReport();
+        mkdirSync(path.dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf-8');
+    }
+    createReport() {
+        const phases = {};
+        for (const [phase, record] of this.phases) {
+            phases[phase] = record;
+        }
+        return {
+            generatedAt: new Date().toISOString(),
+            runtime: typeof Bun !== 'undefined' ? `bun ${Bun.version}` : `node ${process.version}`,
+            platform: process.platform,
+            phases,
+            firstRequest: this.firstRequestPath
+                ? {
+                    path: this.firstRequestPath,
+                    bundleCount: this.firstRequestBundleCount,
+                    clientBundleBytes: this.firstRequestClientBytes,
+                    graphBuildCount: this.firstRequestGraphBuildCount,
+                    wallMs: this.firstRequestCompletedWallMs ?? wallMsSinceProcessStart(),
+                }
+                : undefined,
+            client: this.clientRequestCount > 0 || this.hydrationReadyMs !== null
+                ? {
+                    requestCount: this.clientRequestCount,
+                    transferredBytes: this.clientTransferredBytes,
+                    hmrConnected: this.hmrConnected,
+                    hydrationReadyMs: this.hydrationReadyMs,
+                }
+                : undefined,
+        };
+    }
+    /** Resets mutable trace state for unit tests. */
+    resetForTests() {
+        this.phaseNesting.clear();
+        this.phases.clear();
+        this.firstRequestPending = true;
+        this.firstRequestPath = undefined;
+        this.firstRequestBundleCount = 0;
+        this.firstRequestClientBytes = 0;
+        this.firstRequestGraphBuildCount = 0;
+        this.firstRequestCompletedWallMs = undefined;
+        this.summaryEmitted = false;
+        this.firstPageBrowserGraphEmitted = false;
+        this.devClientTransformEmitted = false;
+        this.clientRequestCount = 0;
+        this.clientTransferredBytes = 0;
+        this.hmrConnected = false;
+        this.hydrationReadyMs = null;
+    }
+    /**
+     * Resets only the first-request bundle counters.
+     *
+     * @remarks
+     * Used by tests that need to re-measure first-request browser bundle work
+     * without clearing earlier startup phase records.
+     */
+    resetFirstRequestCounters() {
+        this.firstRequestBundleCount = 0;
+        this.firstRequestClientBytes = 0;
+        this.firstRequestGraphBuildCount = 0;
+    }
 }
-const startupTrace = new StartupTrace();
-export {
-  startupTrace
-};
+export const startupTrace = new StartupTrace();

package/src/eco/README.md

@@ -14,6 +14,12 @@ The `eco` namespace provides a consistent, type-safe interface for:
 6. **`eco.staticPaths()`** - Type-safe wrapper for dynamic route generation (legacy pattern)
 7. **`eco.staticProps()`** - Type-safe wrapper for static data fetching (legacy pattern)
 
+## Layout assignment
+
+Layouts are assigned explicitly on each `eco.page({ layout })` call — either one layout component or an outer→inner array. EcoPages normalizes the stack at factory time to `config.layouts` and `config.layoutEntries`.
+
+EcoPages does **not** infer layouts from `src/layouts/` file paths or route segment directories. A file under `src/layouts/` is only used when a page imports it and passes it to `layout`.
+
 ## Component Patterns
 
 EcoPages supports two approaches for creating components, each suited for different use cases:

package/src/eco/eco-declared-component.js

@@ -1,16 +1,21 @@
-import { UndeclaredComponentDependencyError } from "../errors/undeclared-component-dependency-error.js";
-import { getUndeclaredComponentDependencyMessage } from "../errors/undeclared-component-dependency-error.js";
-function isEcoDeclaredComponent(component) {
-  return typeof component === "function" && typeof component.config?.__eco?.file === "string" && typeof component.config?.__eco?.integration === "string";
+import { UndeclaredComponentDependencyError } from '../errors/undeclared-component-dependency-error.js';
+export { getUndeclaredComponentDependencyMessage } from '../errors/undeclared-component-dependency-error.js';
+/**
+ * @remarks
+ * Declared components are produced by `eco.component()`, `eco.layout()`, and
+ * `eco.html()` after the component-meta plugin injects `config.__eco`.
+ */
+export function isEcoDeclaredComponent(component) {
+    return (typeof component === 'function' &&
+        typeof component.config?.__eco?.file === 'string' &&
+        typeof component.config?.__eco?.integration === 'string');
 }
-function assertEcoDeclaredComponent(component, context = {}) {
-  if (isEcoDeclaredComponent(component)) {
-    return;
-  }
-  throw new UndeclaredComponentDependencyError(context.parentComponentFile);
+/**
+ * @throws {UndeclaredComponentDependencyError} When the value lacks `config.__eco`.
+ */
+export function assertEcoDeclaredComponent(component, context = {}) {
+    if (isEcoDeclaredComponent(component)) {
+        return;
+    }
+    throw new UndeclaredComponentDependencyError(context.parentComponentFile);
 }
-export {
-  assertEcoDeclaredComponent,
-  getUndeclaredComponentDependencyMessage,
-  isEcoDeclaredComponent
-};