@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.1

package/src/dev-toolbar/dev-toolbar-package.js

@@ -0,0 +1,78 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+const SOURCE_CLIENT_FILE = 'src/bootstrap.ts';
+const COMPILED_CLIENT_FILE = 'src/bootstrap.js';
+/**
+ * Returns the configured dev-toolbar client package specifier, if any.
+ */
+export function getDevToolbarPackageSpec(appConfig) {
+    const spec = appConfig.devToolbar?.package?.trim();
+    return spec || undefined;
+}
+/**
+ * Resolves the dev-toolbar package root from an application project directory.
+ *
+ * @remarks Walks up from the package entry rather than resolving `package.json`
+ * directly so packages with strict `exports` (no `./package.json` subpath) still work.
+ */
+export function resolveDevToolbarPackageRoot(rootDir, packageSpec) {
+    const require = createRequire(path.join(rootDir, 'package.json'));
+    let dir = path.dirname(require.resolve(packageSpec));
+    while (dir !== path.dirname(dir)) {
+        if (fileSystem.exists(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error(`Could not resolve package root for ${packageSpec}`);
+}
+/**
+ * Resolves the browser entrypoint core bundles into `/_dev_toolbar.js`.
+ *
+ * @remarks Prefers `src/bootstrap.js` when present (published npm or `file:` to
+ * `dist`), then `bootstrap.ts` for workspace source checkouts.
+ */
+export function resolveDevToolbarClient(rootDir, packageSpec) {
+    const require = createRequire(path.join(rootDir, 'package.json'));
+    const packageRoot = resolveDevToolbarPackageRoot(rootDir, packageSpec);
+    const entryCandidates = [path.join(packageRoot, COMPILED_CLIENT_FILE), path.join(packageRoot, SOURCE_CLIENT_FILE)];
+    for (const entryPath of entryCandidates) {
+        if (fileSystem.exists(entryPath)) {
+            return { entryPath };
+        }
+    }
+    try {
+        return { entryPath: require.resolve(packageSpec) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the configured dev-toolbar client for an app config, when present.
+ */
+export function resolveConfiguredDevToolbarClient(appConfig) {
+    const packageSpec = getDevToolbarPackageSpec(appConfig);
+    if (!packageSpec) {
+        return undefined;
+    }
+    return resolveDevToolbarClient(appConfig.absolutePaths.projectDir, packageSpec);
+}
+/**
+ * Resolves a dev-toolbar client entry module from the application project root.
+ */
+export function resolveDevToolbarPackageEntry(rootDir, packageSpec) {
+    const client = resolveDevToolbarClient(rootDir, packageSpec);
+    if (!client) {
+        const require = createRequire(path.join(rootDir, 'package.json'));
+        return require.resolve(packageSpec);
+    }
+    return client.entryPath;
+}
+/**
+ * Resolves the configured dev-toolbar entry for an app config, when present.
+ */
+export function resolveConfiguredDevToolbarEntry(appConfig) {
+    return resolveConfiguredDevToolbarClient(appConfig)?.entryPath;
+}

package/src/dev-toolbar/dev-toolbar-runtime-paths.d.ts

@@ -0,0 +1,10 @@
+/** On-disk work directory segment for the bundled dev toolbar client runtime. */
+export declare const DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT = "dev-toolbar-runtime";
+/** Browser URL for the bundled dev toolbar client runtime script. */
+export declare const DEV_TOOLBAR_RUNTIME_SCRIPT_URL = "/_dev_toolbar.js";
+/** Module import emitted into dev HTML responses. */
+export declare const DEV_TOOLBAR_RUNTIME_IMPORT = "import '/_dev_toolbar.js'";
+/**
+ * Absolute work-directory path for dev toolbar runtime artifacts under an app work dir.
+ */
+export declare function resolveDevToolbarRuntimeWorkDir(workDir: string): string;

package/src/dev-toolbar/dev-toolbar-runtime-paths.js

@@ -0,0 +1,13 @@
+import { RESOLVED_ASSETS_DIR } from '../config/constants.js';
+/** On-disk work directory segment for the bundled dev toolbar client runtime. */
+export const DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT = 'dev-toolbar-runtime';
+/** Browser URL for the bundled dev toolbar client runtime script. */
+export const DEV_TOOLBAR_RUNTIME_SCRIPT_URL = '/_dev_toolbar.js';
+/** Module import emitted into dev HTML responses. */
+export const DEV_TOOLBAR_RUNTIME_IMPORT = `import '${DEV_TOOLBAR_RUNTIME_SCRIPT_URL}'`;
+/**
+ * Absolute work-directory path for dev toolbar runtime artifacts under an app work dir.
+ */
+export function resolveDevToolbarRuntimeWorkDir(workDir) {
+    return `${workDir}/${RESOLVED_ASSETS_DIR}/${DEV_TOOLBAR_RUNTIME_WORK_DIR_SEGMENT}`;
+}

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,39 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * 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.
+ */
+class RequestBuildDedupe {
+    storage = new AsyncLocalStorage();
+    run(fn) {
+        if (this.storage.getStore()) {
+            return fn();
+        }
+        return this.storage.run(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;
+    }
+}
+export const requestBuildDedupe = new RequestBuildDedupe();

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();