@ecopages/core 0.2.0-beta.38 → 0.2.0-beta.39

package/src/cache/index.js

@@ -3,4 +3,5 @@
  *
  * @module @ecopages/core/cache
  */
-export { ModuleParseCache, moduleParseCache, cachedParseSync } from './module-parse-cache.js';
+export { ModuleParseCache, moduleParseCache, cachedParseSync, parseModuleSource, parserLanguageForFile, } from './module-parse-cache.js';
+export { recordModuleTransformProfile } from './module-transform-profiler.js';

package/src/cache/module-parse-cache.d.ts

@@ -22,6 +22,11 @@ export type ModuleParseOptions = ParserOptions & {
      */
     lang?: ParserOptions['lang'];
 };
+export type ParserLanguage = 'js' | 'jsx' | 'ts' | 'tsx';
+/** Resolves the Oxc dialect for a source module from its file extension. */
+export declare function parserLanguageForFile(filePath: string): ParserLanguage;
+/** Parses an ECMAScript module with the shared, normalized cache contract. */
+export declare function parseModuleSource(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;
 /**
  * LRU-bounded module parse cache.
  *

package/src/cache/module-parse-cache.js

@@ -13,9 +13,25 @@
  * mtime-hashed so that `touch`/`utimes` does not invalidate a
  * still-valid parse.
  */
+import { extname } from 'node:path';
 import { parseSync } from 'oxc-parser';
 import { rapidhash } from '../utils/hash.js';
 const DEFAULT_MAX_ENTRIES = 10_000;
+/** Resolves the Oxc dialect for a source module from its file extension. */
+export function parserLanguageForFile(filePath) {
+    const extension = extname(filePath).toLowerCase();
+    if (extension === '.tsx')
+        return 'tsx';
+    if (extension === '.ts' || extension === '.mts' || extension === '.cts')
+        return 'ts';
+    if (extension === '.jsx')
+        return 'jsx';
+    return 'js';
+}
+/** Parses an ECMAScript module with the shared, normalized cache contract. */
+export function parseModuleSource(filePath, source, options = {}) {
+    return moduleParseCache.getOrParse(filePath, source, normalizeModuleParseOptions(filePath, options));
+}
 /**
  * LRU-bounded module parse cache.
  *
@@ -39,8 +55,9 @@ export class ModuleParseCache {
      * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
      */
     getOrParse(filePath, source, options = {}) {
+        const normalizedOptions = normalizeModuleParseOptions(filePath, options);
         const hash = rapidhash(source);
-        const key = makeKey(filePath, hash, options);
+        const key = makeKey(filePath, hash, normalizedOptions);
         const existing = this.entries.get(key);
         if (existing && existing.hash === hash) {
             this.hits += 1;
@@ -50,7 +67,7 @@ export class ModuleParseCache {
             return existing.result;
         }
         this.misses += 1;
-        const result = parseSync(filePath, source, options);
+        const result = parseSync(filePath, source, normalizedOptions);
         this.entries.set(key, { hash, result });
         if (this.entries.size > this.maxEntries) {
             // Map iteration order is insertion order; the first key is the
@@ -95,7 +112,14 @@ export const moduleParseCache = new ModuleParseCache();
  * on user/source files during a build.
  */
 export function cachedParseSync(filePath, source, options = {}) {
-    return moduleParseCache.getOrParse(filePath, source, options);
+    return parseModuleSource(filePath, source, options);
+}
+function normalizeModuleParseOptions(filePath, options) {
+    return {
+        ...options,
+        lang: options.lang ?? parserLanguageForFile(filePath),
+        sourceType: options.sourceType ?? 'module',
+    };
 }
 function makeKey(filePath, sourceHash, options) {
     // Stringify only the option keys we actually use; `parseSync` does

package/src/cache/module-transform-profiler.d.ts

@@ -0,0 +1,8 @@
+type ProfileRecord = {
+    category: string;
+    phase: string;
+    ms: number;
+    cacheHit?: boolean;
+};
+export declare function recordModuleTransformProfile(record: ProfileRecord): void;
+export {};

package/src/cache/module-transform-profiler.js

@@ -0,0 +1,8 @@
+export function recordModuleTransformProfile(record) {
+    if (process.env.ECO_AST_PROFILE !== '1')
+        return;
+    console.info(`[ecopages:ast-profile] ${JSON.stringify({
+        ...record,
+        ms: Number(record.ms.toFixed(3)),
+    })}`);
+}

package/src/client/view-transitions.d.ts

@@ -1,7 +1,23 @@
 /**
- * View Transition API helpers for `data-view-transition` markup.
+ * View Transition API helpers for `data-view-transition` markup and safe root defaults.
  * @module
  */
+/**
+ * Whether a document tree contains elements that participate in named view transitions.
+ */
+export declare function documentHasNamedViewTransitions(doc: Document): boolean;
+/**
+ * Whether SPA navigation should use `startViewTransition` (old or incoming page).
+ */
+export declare function navigationHasNamedViewTransitions(current: Document, incoming: Document): boolean;
+/**
+ * Injects persisted CSS that opts the document out of the root view-transition group.
+ *
+ * @remarks
+ * Uses `data-eco-persist` so head morphing does not drop the stylesheet between navigations.
+ * Named `data-view-transition` morph / fade rules live in a separate dynamic style tag.
+ */
+export declare function ensureRootViewTransitionStyles(): void;
 /**
  * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
  *

package/src/client/view-transitions.js

@@ -1,11 +1,55 @@
 /**
- * View Transition API helpers for `data-view-transition` markup.
+ * View Transition API helpers for `data-view-transition` markup and safe root defaults.
  * @module
  */
 const VIEW_TRANSITION_ATTR = 'data-view-transition';
 const VIEW_TRANSITION_ANIMATE_ATTR = 'data-view-transition-animate';
 const VIEW_TRANSITION_DURATION_ATTR = 'data-view-transition-duration';
 const DYNAMIC_STYLES_ID = 'eco-vt-dynamic-styles';
+const ROOT_STYLES_ID = 'eco-vt-root-styles';
+/**
+ * @remarks
+ * UA default is `html { view-transition-name: root }`, which snapshots the whole
+ * document and crossfades with plus-lighter (flashes lighter on dark UIs). Routers
+ * inject this opt-out when `viewTransitions` is enabled. Named `data-view-transition`
+ * morphs still run. Full-page fades are not a supported default — use named elements
+ * or app-owned motion outside the View Transitions API.
+ */
+const ROOT_STYLES_CSS = `html {
+	view-transition-name: none;
+}
+`;
+/**
+ * Whether a document tree contains elements that participate in named view transitions.
+ */
+export function documentHasNamedViewTransitions(doc) {
+    return doc.querySelector(`[${VIEW_TRANSITION_ATTR}]`) !== null;
+}
+/**
+ * Whether SPA navigation should use `startViewTransition` (old or incoming page).
+ */
+export function navigationHasNamedViewTransitions(current, incoming) {
+    return documentHasNamedViewTransitions(current) || documentHasNamedViewTransitions(incoming);
+}
+/**
+ * Injects persisted CSS that opts the document out of the root view-transition group.
+ *
+ * @remarks
+ * Uses `data-eco-persist` so head morphing does not drop the stylesheet between navigations.
+ * Named `data-view-transition` morph / fade rules live in a separate dynamic style tag.
+ */
+export function ensureRootViewTransitionStyles() {
+    let styleEl = document.getElementById(ROOT_STYLES_ID);
+    if (!styleEl) {
+        styleEl = document.createElement('style');
+        styleEl.id = ROOT_STYLES_ID;
+        styleEl.setAttribute('data-eco-persist', '');
+        document.head.append(styleEl);
+    }
+    if (styleEl.textContent !== ROOT_STYLES_CSS) {
+        styleEl.textContent = ROOT_STYLES_CSS;
+    }
+}
 /**
  * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
  *

package/src/client/view-transitions.test.browser.d.ts

@@ -0,0 +1 @@
+export {};

package/src/client/view-transitions.test.browser.js

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { applyViewTransitionNames, clearViewTransitionNames, documentHasNamedViewTransitions, ensureRootViewTransitionStyles, navigationHasNamedViewTransitions, } from './view-transitions.js';
+describe('documentHasNamedViewTransitions', () => {
+    afterEach(() => {
+        document.body.replaceChildren();
+    });
+    it('returns false when no markup is present', () => {
+        expect(documentHasNamedViewTransitions(document)).toBe(false);
+    });
+    it('returns true when data-view-transition is present', () => {
+        document.body.innerHTML = '<div data-view-transition="x"></div>';
+        expect(documentHasNamedViewTransitions(document)).toBe(true);
+    });
+    it('navigation checks current or incoming document', () => {
+        const incoming = new DOMParser().parseFromString('<html><body><div data-view-transition="hero"></div></body></html>', 'text/html');
+        expect(navigationHasNamedViewTransitions(document, incoming)).toBe(true);
+    });
+});
+describe('ensureRootViewTransitionStyles', () => {
+    afterEach(() => {
+        document.getElementById('eco-vt-root-styles')?.remove();
+        document.getElementById('eco-vt-dynamic-styles')?.remove();
+        document.body.replaceChildren();
+    });
+    it('opts the document out of the root view-transition group without !important', () => {
+        ensureRootViewTransitionStyles();
+        const style = document.getElementById('eco-vt-root-styles');
+        expect(style).not.toBeNull();
+        expect(style?.hasAttribute('data-eco-persist')).toBe(true);
+        expect(style?.textContent).toContain('view-transition-name: none');
+        expect(style?.textContent).not.toContain('!important');
+        expect(getComputedStyle(document.documentElement).viewTransitionName).toBe('none');
+    });
+    it('reuses a single style element', () => {
+        ensureRootViewTransitionStyles();
+        ensureRootViewTransitionStyles();
+        expect(document.querySelectorAll('#eco-vt-root-styles')).toHaveLength(1);
+    });
+});
+describe('applyViewTransitionNames with root styles', () => {
+    afterEach(() => {
+        document.getElementById('eco-vt-root-styles')?.remove();
+        document.getElementById('eco-vt-dynamic-styles')?.remove();
+        document.body.replaceChildren();
+    });
+    it('keeps root styles when clearing named morph styles', () => {
+        ensureRootViewTransitionStyles();
+        document.body.innerHTML = '<div data-view-transition="hero"></div>';
+        applyViewTransitionNames();
+        expect(document.getElementById('eco-vt-dynamic-styles')?.textContent).toContain('view-transition-old(hero)');
+        expect(document.getElementById('eco-vt-root-styles')?.textContent).toContain('view-transition-name: none');
+        clearViewTransitionNames();
+        expect(document.getElementById('eco-vt-dynamic-styles')?.textContent).toBe('');
+        expect(document.getElementById('eco-vt-root-styles')?.textContent).toContain('view-transition-name: none');
+    });
+});

package/src/config/config-builder.d.ts

@@ -198,6 +198,20 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setAdditionalWatchPaths(additionalWatchPaths: string[]): this;
+    /**
+     * Sets static paths to SSR-prewarm in development.
+     *
+     * @param devPrewarmPaths - Absolute URL pathnames such as `/` or `/docs`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmPaths(devPrewarmPaths: string[]): this;
+    /**
+     * Sets static paths to SSR-prewarm before the development server reports ready.
+     *
+     * @param devPrewarmBeforeReadyPaths - Critical absolute URL pathnames such as `/`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmBeforeReadyPaths(devPrewarmBeforeReadyPaths: string[]): this;
     /**
      * Sets the processors to use for the application.
      * This replaces any existing processors.
@@ -265,15 +279,8 @@ export declare class ConfigBuilder {
      * Initializes default loaders that are required for EcoPages to function.
      *
      * @remarks
-     * `eco-component-meta` is registered twice on purpose:
-     *
-     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
-     *   runs these after first-wins `onLoad` plugins rewrite module source.
-     * - `loaders` keeps the same transform available to server-oriented builds
-     *   that still use competing `onLoad` handlers directly.
-     *
-     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
-     * when the transform name is already present in `sourceTransforms`.
+     * Component identity attribution is a source transform so browser, HMR, and
+     * server module paths share one component-identity attribution mechanism.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;

package/src/config/config-builder.js

@@ -7,7 +7,6 @@ import { DEFAULT_ECOPAGES_DIST_DIR, DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_
 import { collectConfiguredAppBuildManifestContributions, createBuildAdapter, setAppBuildAdapter, updateAppBuildManifest, } from '../build/build-adapter.js';
 import { GHTML_PLUGIN_NAME } from '../integrations/ghtml/ghtml.constants.js';
 import { ghtmlPlugin } from '../integrations/ghtml/ghtml.plugin.js';
-import { createEcoComponentMetaPlugin } from '../plugins/eco-component-meta-plugin.js';
 import { createEcoComponentMetaTransform } from '../plugins/eco-component-meta-plugin.js';
 import { NoopEntrypointDependencyGraph, setAppEntrypointDependencyGraph, } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
 import { CounterServerInvalidationState, setAppServerInvalidationState, } from '../services/runtime-state/server-invalidation-state.service.js';
@@ -76,6 +75,8 @@ export class ConfigBuilder {
             description: 'This is a static site generated with Ecopages',
         },
         additionalWatchPaths: [],
+        devPrewarmPaths: [],
+        devPrewarmBeforeReadyPaths: [],
         templatesExt: [],
         absolutePaths: {
             config: '',
@@ -316,6 +317,26 @@ export class ConfigBuilder {
         this.config.additionalWatchPaths = additionalWatchPaths;
         return this;
     }
+    /**
+     * Sets static paths to SSR-prewarm in development.
+     *
+     * @param devPrewarmPaths - Absolute URL pathnames such as `/` or `/docs`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmPaths(devPrewarmPaths) {
+        this.config.devPrewarmPaths = devPrewarmPaths;
+        return this;
+    }
+    /**
+     * Sets static paths to SSR-prewarm before the development server reports ready.
+     *
+     * @param devPrewarmBeforeReadyPaths - Critical absolute URL pathnames such as `/`.
+     * @returns The ConfigBuilder instance for method chaining.
+     */
+    setDevPrewarmBeforeReadyPaths(devPrewarmBeforeReadyPaths) {
+        this.config.devPrewarmBeforeReadyPaths = devPrewarmBeforeReadyPaths;
+        return this;
+    }
     /**
      * Sets the processors to use for the application.
      * This replaces any existing processors.
@@ -580,25 +601,14 @@ export class ConfigBuilder {
      * Initializes default loaders that are required for EcoPages to function.
      *
      * @remarks
-     * `eco-component-meta` is registered twice on purpose:
-     *
-     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
-     *   runs these after first-wins `onLoad` plugins rewrite module source.
-     * - `loaders` keeps the same transform available to server-oriented builds
-     *   that still use competing `onLoad` handlers directly.
-     *
-     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
-     * when the transform name is already present in `sourceTransforms`.
+     * Component identity attribution is a source transform so browser, HMR, and
+     * server module paths share one component-identity attribution mechanism.
      */
     async initializeDefaultLoaders() {
         const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
         if (!this.config.sourceTransforms.has(componentMetaTransform.name)) {
             this.config.sourceTransforms.set(componentMetaTransform.name, componentMetaTransform);
         }
-        const componentMetaPlugin = createEcoComponentMetaPlugin({ config: this.config });
-        if (!this.config.loaders.has(componentMetaPlugin.name)) {
-            this.config.loaders.set(componentMetaPlugin.name, componentMetaPlugin);
-        }
     }
     reviewBaseUrl(baseUrl) {
         if (baseUrl) {

package/src/dev/transform-server/dev-transform-vendor-registry.d.ts

@@ -22,6 +22,7 @@ export declare class DevTransformVendorRegistry {
     tryHandleVendorRequest(pathname: string): Response | null;
     invalidateAll(): void;
     private createVendorResponse;
+    private resolveExistingVendorPath;
     private prebundleSpecifier;
     private resolvePackageEntry;
 }

package/src/dev/transform-server/dev-transform-vendor-registry.js

@@ -31,7 +31,7 @@ export class DevTransformVendorRegistry {
     }
     async resolveVendorUrl(specifier) {
         const known = this.resolveKnownVendorUrl(specifier);
-        if (known) {
+        if (known && this.resolveExistingVendorPath(known)) {
             return known;
         }
         const cached = this.cache.get(specifier);
@@ -60,7 +60,7 @@ export class DevTransformVendorRegistry {
         const filePath = path.join(this.vendorsDir, fileName);
         if (!fileSystem.exists(filePath)) {
             for (const entry of this.cache.values()) {
-                if (entry.url === pathname) {
+                if (entry.url === pathname && fileSystem.exists(entry.filePath)) {
                     return this.createVendorResponse(entry.filePath);
                 }
             }
@@ -80,6 +80,19 @@ export class DevTransformVendorRegistry {
             },
         });
     }
+    resolveExistingVendorPath(url) {
+        const prefix = `/${RESOLVED_ASSETS_VENDORS_DIR}/`;
+        const pathname = new URL(url, 'http://ecopages.local').pathname;
+        if (!pathname.startsWith(prefix)) {
+            return undefined;
+        }
+        const fileName = pathname.slice(prefix.length);
+        if (!fileName || fileName.includes('..')) {
+            return undefined;
+        }
+        const filePath = path.join(this.vendorsDir, fileName);
+        return fileSystem.exists(filePath) ? filePath : undefined;
+    }
     async prebundleSpecifier(specifier) {
         const resolvedEntry = this.resolvePackageEntry(specifier);
         fileSystem.ensureDir(this.vendorsDir);

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/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

@@ -3,11 +3,12 @@ export { getUndeclaredComponentDependencyMessage } from '../errors/undeclared-co
 /**
  * @remarks
  * Declared components are produced by `eco.component()`, `eco.layout()`, and
- * `eco.html()` after the component-meta plugin injects `config.__eco`.
+ * `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 `config.__eco`.
+ * @throws {UndeclaredComponentDependencyError} When the value lacks component identity.
  */
 export declare function assertEcoDeclaredComponent(component: unknown, context?: {
     parentComponentFile?: string;

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

@@ -1,17 +1,19 @@
 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-meta plugin injects `config.__eco`.
+ * `eco.html()` after the component identity transform binds identity via
+ * `bindComponentIdentity`.
  */
 export function isEcoDeclaredComponent(component) {
     return (typeof component === 'function' &&
-        typeof component.config?.__eco?.file === 'string' &&
-        typeof component.config?.__eco?.integration === 'string');
+        typeof getComponentIdentity(component)?.file === 'string' &&
+        typeof getComponentIdentity(component)?.integration === 'string');
 }
 /**
- * @throws {UndeclaredComponentDependencyError} When the value lacks `config.__eco`.
+ * @throws {UndeclaredComponentDependencyError} When the value lacks component identity.
  */
 export function assertEcoDeclaredComponent(component, context = {}) {
     if (isEcoDeclaredComponent(component)) {

package/src/eco/eco.browser.js

@@ -2,7 +2,7 @@ import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts }
 function createComponentFactory(options) {
     const component = ((props) => options.render(props));
     component.config = {
-        __eco: options.__eco,
+        identity: options.identity,
         integration: options.integration,
         dependencies: options.dependencies,
     };
@@ -29,7 +29,7 @@ function page(options) {
         ? mergeLayoutDependencies(undefined, layoutEntries)
         : mergeLayoutDependencies(dependenciesInput, layoutEntries);
     const pageComponent = createComponentFactory({
-        __eco: options.__eco,
+        identity: options.identity,
         integration: options.integration,
         dependencies: staticDependencies,
         render,