@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

package/src/diagnostics/request-pipeline-metrics.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-request and process-wide counters for the development render pipeline.
+ *
+ * @remarks
+ * Gated behind {@link isRequestPipelineMetricsEnabled} so production paths stay quiet.
+ * Benchmarks and structural invariant tests read the snapshot via
+ * {@link getRequestPipelineMetricsSnapshot}.
+ */
+export type PageModuleLoadOutcome = 'import-cache-hit' | 'disk-cache-hit' | 'cold-build' | 'host-loader' | 'unified-graph';
+export type RouteRenderPhase = 'resolve-route-inputs' | 'ownership-validation' | 'resolve-dependencies' | 'page-browser-graph' | 'render-body' | 'transform-response';
+export type RouteRenderPhaseRecord = {
+    count: number;
+    totalDurationMs: number;
+    lastDurationMs: number;
+};
+export type RequestPipelineMetricsSnapshot = {
+    runtime: 'node' | 'bun';
+    pageModuleLoads: number;
+    pageModuleBuilds: number;
+    pageModuleCacheHits: number;
+    hostLoaderLoads: number;
+    diskCacheHits: number;
+    routeModuleArtifacts: number;
+    mdxTransforms: number;
+    collectionBuilds: number;
+    routeRenderPhases: Partial<Record<RouteRenderPhase, RouteRenderPhaseRecord>>;
+};
+export declare function isRequestPipelineMetricsEnabled(): boolean;
+export declare function getRequestPipelineMetricsHeaderName(): string;
+export declare function resolveRequestPipelineRuntime(): 'node' | 'bun';
+export declare function recordPageModuleLoad(outcome: PageModuleLoadOutcome, artifactCount?: number): void;
+export declare function recordMdxTransform(): void;
+export declare function recordCollectionBuild(): void;
+export declare function recordRouteRenderPhase(phase: RouteRenderPhase, durationMs: number): void;
+export declare function measureRouteRenderPhase<T>(phase: RouteRenderPhase, fn: () => Promise<T>): Promise<T>;
+export declare function getRequestPipelineMetricsSnapshot(): RequestPipelineMetricsSnapshot;
+export declare function serializeRequestPipelineMetricsHeader(): string;
+export declare function resetRequestPipelineMetrics(): void;

package/src/diagnostics/request-pipeline-metrics.js

@@ -0,0 +1,121 @@
+/**
+ * Per-request and process-wide counters for the development render pipeline.
+ *
+ * @remarks
+ * Gated behind {@link isRequestPipelineMetricsEnabled} so production paths stay quiet.
+ * Benchmarks and structural invariant tests read the snapshot via
+ * {@link getRequestPipelineMetricsSnapshot}.
+ */
+const METRICS_HEADER = 'x-ecopages-pipeline-metrics';
+let pageModuleLoads = 0;
+let pageModuleBuilds = 0;
+let pageModuleCacheHits = 0;
+let hostLoaderLoads = 0;
+let diskCacheHits = 0;
+let routeModuleArtifacts = 0;
+let mdxTransforms = 0;
+let collectionBuilds = 0;
+const routeRenderPhases = new Map();
+export function isRequestPipelineMetricsEnabled() {
+    return (process.env.ECOPAGES_REQUEST_PIPELINE_METRICS === '1' ||
+        process.env.ECOPAGES_ROLLDOWN_BUILD_METRICS === '1' ||
+        process.env.ECOPAGES_LOGGER_DEBUG === 'true');
+}
+export function getRequestPipelineMetricsHeaderName() {
+    return METRICS_HEADER;
+}
+export function resolveRequestPipelineRuntime() {
+    return typeof Bun !== 'undefined' ? 'bun' : 'node';
+}
+export function recordPageModuleLoad(outcome, artifactCount = 0) {
+    if (!isRequestPipelineMetricsEnabled()) {
+        return;
+    }
+    pageModuleLoads += 1;
+    switch (outcome) {
+        case 'import-cache-hit':
+            pageModuleCacheHits += 1;
+            break;
+        case 'disk-cache-hit':
+            diskCacheHits += 1;
+            break;
+        case 'cold-build':
+            pageModuleBuilds += 1;
+            routeModuleArtifacts += artifactCount;
+            break;
+        case 'host-loader':
+            hostLoaderLoads += 1;
+            break;
+        case 'unified-graph':
+            break;
+    }
+}
+export function recordMdxTransform() {
+    if (!isRequestPipelineMetricsEnabled()) {
+        return;
+    }
+    mdxTransforms += 1;
+}
+export function recordCollectionBuild() {
+    if (!isRequestPipelineMetricsEnabled()) {
+        return;
+    }
+    collectionBuilds += 1;
+}
+export function recordRouteRenderPhase(phase, durationMs) {
+    if (!isRequestPipelineMetricsEnabled()) {
+        return;
+    }
+    const existing = routeRenderPhases.get(phase);
+    if (existing) {
+        existing.count += 1;
+        existing.totalDurationMs += durationMs;
+        existing.lastDurationMs = durationMs;
+        return;
+    }
+    routeRenderPhases.set(phase, {
+        count: 1,
+        totalDurationMs: durationMs,
+        lastDurationMs: durationMs,
+    });
+}
+export async function measureRouteRenderPhase(phase, fn) {
+    if (!isRequestPipelineMetricsEnabled()) {
+        return fn();
+    }
+    const startedAt = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        recordRouteRenderPhase(phase, performance.now() - startedAt);
+    }
+}
+export function getRequestPipelineMetricsSnapshot() {
+    return {
+        runtime: resolveRequestPipelineRuntime(),
+        pageModuleLoads,
+        pageModuleBuilds,
+        pageModuleCacheHits,
+        hostLoaderLoads,
+        diskCacheHits,
+        routeModuleArtifacts,
+        mdxTransforms,
+        collectionBuilds,
+        routeRenderPhases: Object.fromEntries(routeRenderPhases),
+    };
+}
+export function serializeRequestPipelineMetricsHeader() {
+    return JSON.stringify(getRequestPipelineMetricsSnapshot());
+}
+export function resetRequestPipelineMetrics() {
+    pageModuleLoads = 0;
+    pageModuleBuilds = 0;
+    pageModuleCacheHits = 0;
+    hostLoaderLoads = 0;
+    diskCacheHits = 0;
+    routeModuleArtifacts = 0;
+    mdxTransforms = 0;
+    collectionBuilds = 0;
+    routeRenderPhases.clear();
+}

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

@@ -0,0 +1,81 @@
+export type StartupTracePhase = 'config-ready' | 'setupAppRuntimePlugins' | 'route-registry' | 'server-listen' | 'first-byte' | 'first-page-browser-graph' | 'dev-client-transform' | 'first-request-ssr' | 'client-transfer' | 'client-hydration';
+type PhaseRecord = {
+    durationMs: number;
+    wallMs: number;
+};
+export type StartupTraceReport = {
+    generatedAt: string;
+    runtime: string;
+    platform: string;
+    phases: Partial<Record<StartupTracePhase, PhaseRecord>>;
+    firstRequest?: {
+        path: string;
+        bundleCount: number;
+        clientBundleBytes: number;
+        graphBuildCount: number;
+        wallMs: number;
+    };
+    client?: {
+        requestCount: number;
+        transferredBytes: number;
+        hmrConnected: boolean;
+        hydrationReadyMs: number | null;
+    };
+};
+declare class StartupTrace {
+    private readonly phaseNesting;
+    private readonly phases;
+    private firstRequestPending;
+    private firstRequestPath;
+    private firstRequestBundleCount;
+    private firstRequestClientBytes;
+    private firstRequestGraphBuildCount;
+    private firstRequestCompletedWallMs;
+    private summaryEmitted;
+    private firstPageBrowserGraphEmitted;
+    private devClientTransformEmitted;
+    private clientRequestCount;
+    private clientTransferredBytes;
+    private hmrConnected;
+    private hydrationReadyMs;
+    isEnabled(): boolean;
+    markPhaseStart(phase: StartupTracePhase): void;
+    markPhaseEnd(phase: StartupTracePhase): void;
+    markConfigReady(): void;
+    markServerListening(): void;
+    beginServerListen(): void;
+    markFirstByte(): void;
+    beginFirstByte(): void;
+    beginDevClientTransform(): void;
+    endDevClientTransform(): void;
+    /**
+     * 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?: number): void;
+    recordBrowserBundle(outputs: Array<{
+        path: string;
+    }>): void;
+    recordClientTransfer(requestCount: number, transferredBytes: number): void;
+    beginClientTransfer(): void;
+    recordClientHydration(durationMs: number): void;
+    beginClientHydration(): void;
+    recordHmrConnected(): void;
+    traceFirstRequest<T>(request: Request, handler: () => Promise<T>): Promise<T>;
+    private emitFirstRequestSummary;
+    private writeJsonReport;
+    createReport(): StartupTraceReport;
+    /** Resets mutable trace state for unit tests. */
+    resetForTests(): void;
+    /**
+     * 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(): void;
+}
+export declare const startupTrace: StartupTrace;
+export {};

package/src/diagnostics/startup-trace.js

@@ -0,0 +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]';
+function isStartupTraceEnabled() {
+    return process.env.ECOPAGES_STARTUP_TRACE === 'true' || process.env.ECOPAGES_LOGGER_DEBUG === 'true';
+}
+function wallMsSinceProcessStart() {
+    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()));
+}
+function writeTraceLine(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 : undefined;
+}
+class StartupTrace {
+    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;
+    }
+}
+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:
@@ -279,6 +285,17 @@ export default eco.page({
 });
 ```
 
+**Nested layouts (outer → inner):**
+
+```tsx
+export default eco.page({
+	layout: [MarketingShell, DocsShell],
+	render: () => <h1>Hello</h1>,
+});
+```
+
+A single layout remains equivalent to a one-element array. Normalization stores the stack on `config.layouts` and `config.layoutEntries` at factory time.
+
 ### `eco.component()`
 
 Define a reusable component with dependencies.

package/src/eco/component-identity.d.ts

@@ -0,0 +1,13 @@
+import type { EcoComponent, EcoComponentConfig } from '../types/public-types.js';
+/** Stable attribution for a Component created by an Integration-owned module. */
+export type ComponentIdentity = {
+    id: string;
+    file: string;
+    integration: string;
+};
+/** Gets canonical component attribution. */
+export declare function getComponentIdentity(value: EcoComponent | EcoComponentConfig | undefined): ComponentIdentity | undefined;
+/** Merges attribution into factory options. */
+export declare function bindComponentIdentity<T extends object>(identity: ComponentIdentity, options: T): T & {
+    identity: ComponentIdentity;
+};

package/src/eco/component-identity.js

@@ -0,0 +1,18 @@
+function asConfig(value) {
+    if (!value)
+        return undefined;
+    if (typeof value === 'function')
+        return value.config;
+    if ('config' in value)
+        return value.config;
+    return value;
+}
+/** Gets canonical component attribution. */
+export function getComponentIdentity(value) {
+    const config = asConfig(value);
+    return config?.identity;
+}
+/** Merges attribution into factory options. */
+export function bindComponentIdentity(identity, options) {
+    return { ...options, identity };
+}

package/src/eco/eco-declared-component.d.ts

@@ -0,0 +1,15 @@
+import type { EcoDeclaredComponent } from '../types/public-types.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 identity transform binds identity via
+ * `bindComponentIdentity`.
+ */
+export declare function isEcoDeclaredComponent(component: unknown): component is EcoDeclaredComponent;
+/**
+ * @throws {UndeclaredComponentDependencyError} When the value lacks component identity.
+ */
+export declare function assertEcoDeclaredComponent(component: unknown, context?: {
+    parentComponentFile?: string;
+}): asserts component is EcoDeclaredComponent;

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

@@ -0,0 +1,23 @@
+import { UndeclaredComponentDependencyError } from '../errors/undeclared-component-dependency-error.js';
+import { getComponentIdentity } from './component-identity.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 identity transform binds identity via
+ * `bindComponentIdentity`.
+ */
+export function isEcoDeclaredComponent(component) {
+    return (typeof component === 'function' &&
+        typeof getComponentIdentity(component)?.file === 'string' &&
+        typeof getComponentIdentity(component)?.integration === 'string');
+}
+/**
+ * @throws {UndeclaredComponentDependencyError} When the value lacks component identity.
+ */
+export function assertEcoDeclaredComponent(component, context = {}) {
+    if (isEcoDeclaredComponent(component)) {
+        return;
+    }
+    throw new UndeclaredComponentDependencyError(context.parentComponentFile);
+}