@ecopages/core 0.2.0-rc.3 → 0.2.0-rc.5

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.d.ts

@@ -1,10 +1,7 @@
 import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
 import type { EcoComponent, ResolvedLazyTrigger } from '../../../types/public-types.js';
-import type { AssetDefinition } from '../../../services/assets/asset-processing-service/index.js';
-import type { AssetProcessingService, ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 export declare function collectIntegrationNamesFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Set<string>;
 export declare function collectResolvedLazyTriggersFromGraph(components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ResolvedLazyTrigger[];
 export declare function hasForeignChildDescendantsInGraph(component: EcoComponent, currentIntegrationName: string): boolean;
-export declare function collectEagerSsrLazyScriptDefinitions(components: (EcoComponent | Partial<EcoComponent>)[]): AssetDefinition[];
 export declare function collectUsedIntegrationDependenciesFromGraph(appConfig: EcoPagesAppConfig, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): ProcessedAsset[];
-export declare function buildEagerSsrLazyAssetsFromGraph(assetProcessingService: AssetProcessingService, components: (EcoComponent | Partial<EcoComponent>)[], currentIntegrationName: string): Promise<ProcessedAsset[]>;

package/src/route-renderer/orchestration/ownership-graph/component-graph-collectors.js

@@ -1,5 +1,3 @@
-import path from 'node:path';
-import { AssetFactory } from '../../../services/assets/asset-processing-service/index.js';
 import { walkComponentGraph } from './component-graph.js';
 import { getComponentIdentity } from '../../../eco/component-identity.js';
 function toGraphRoots(components) {
@@ -51,63 +49,6 @@ export function hasForeignChildDescendantsInGraph(component, currentIntegrationN
     });
     return foundForeign;
 }
-export function collectEagerSsrLazyScriptDefinitions(components) {
-    const dependencies = [];
-    const seenKeys = new Set();
-    const normalizeAttributes = (attributes) => ({
-        type: 'module',
-        defer: '',
-        ...(attributes ?? {}),
-    });
-    walkComponentGraph({
-        roots: toGraphRoots(components),
-        currentIntegrationName: '',
-        visitLayout: true,
-        onConfig: (config) => {
-            const componentFile = getComponentIdentity(config)?.file;
-            if (!componentFile || !config) {
-                return;
-            }
-            const componentDir = path.dirname(componentFile);
-            for (const script of config.dependencies?.scripts ?? []) {
-                if (typeof script === 'string' || !script.lazy || script.ssr !== true) {
-                    continue;
-                }
-                const attributes = normalizeAttributes(script.attributes);
-                if (script.content) {
-                    const key = `content:${script.content}:${JSON.stringify(attributes)}`;
-                    if (seenKeys.has(key)) {
-                        continue;
-                    }
-                    seenKeys.add(key);
-                    dependencies.push(AssetFactory.createContentScript({
-                        position: 'head',
-                        content: script.content,
-                        attributes,
-                        packageRole: 'dynamic-chunk',
-                    }));
-                    continue;
-                }
-                if (!script.src) {
-                    continue;
-                }
-                const resolvedPath = path.resolve(componentDir, script.src);
-                const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
-                if (seenKeys.has(key)) {
-                    continue;
-                }
-                seenKeys.add(key);
-                dependencies.push(AssetFactory.createFileScript({
-                    filepath: resolvedPath,
-                    position: 'head',
-                    attributes,
-                    packageRole: 'dynamic-chunk',
-                }));
-            }
-        },
-    });
-    return dependencies;
-}
 export function collectUsedIntegrationDependenciesFromGraph(appConfig, components, currentIntegrationName) {
     const integrationNames = collectIntegrationNamesFromGraph(components, currentIntegrationName);
     const dependencies = [];
@@ -123,10 +64,3 @@ export function collectUsedIntegrationDependenciesFromGraph(appConfig, component
     }
     return dependencies;
 }
-export async function buildEagerSsrLazyAssetsFromGraph(assetProcessingService, components, currentIntegrationName) {
-    const dependencies = collectEagerSsrLazyScriptDefinitions(components);
-    if (dependencies.length === 0) {
-        return [];
-    }
-    return assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
-}

package/src/route-renderer/orchestration/route-pipeline/route-render-orchestrator.js

@@ -2,7 +2,7 @@ import { collectHtmlCacheSourceDependencyPaths } from '../../../services/cache/h
 import { getComponentIdentity } from '../../../eco/component-identity.js';
 import { inspectUnresolvedMarkerArtifactHtml } from './marker-artifact.utils.js';
 import { OwnershipValidationService, throwIfOwnershipInvalid, } from '../ownership-graph/ownership-validation.service.js';
-import { buildEagerSsrLazyAssetsFromGraph, collectResolvedLazyTriggersFromGraph, collectUsedIntegrationDependenciesFromGraph, } from '../ownership-graph/component-graph-collectors.js';
+import { collectResolvedLazyTriggersFromGraph, collectUsedIntegrationDependenciesFromGraph, } from '../ownership-graph/component-graph-collectors.js';
 import { buildGlobalInjectorAssets } from '../page-browser-graph/global-injector-assets.service.js';
 import { mergePageBrowserGraphContributions } from '../page-browser-graph/page-browser-graph-contribution.merge.js';
 import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
@@ -93,13 +93,10 @@ export class RouteRenderOrchestrator {
             ...collectUsedIntegrationDependenciesFromGraph(this.appConfig, componentsToResolve, adapter.name),
         ];
         const triggers = collectResolvedLazyTriggersFromGraph(componentsToResolve, adapter.name);
-        const [globalAssets, eagerSsrLazyAssets] = await Promise.all([
-            triggers.length > 0
-                ? buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name)
-                : Promise.resolve([]),
-            buildEagerSsrLazyAssetsFromGraph(this.assetProcessingService, componentsToResolve, adapter.name),
-        ]);
-        allDependencies.push(...globalAssets, ...eagerSsrLazyAssets);
+        const globalAssets = triggers.length > 0
+            ? await buildGlobalInjectorAssets(this.appConfig, this.assetProcessingService, triggers, adapter.name)
+            : [];
+        allDependencies.push(...globalAssets);
         const sourceDependencyPaths = collectHtmlCacheSourceDependencyPaths({
             routeFile: routeOptions.file,
             processedAssets: allDependencies,

package/src/route-renderer/page-loading/component-dependency-collection.d.ts

@@ -30,8 +30,12 @@ type CollectComponentDependenciesOptions = {
  * Walks component dependency trees and collects declared assets, module declarations,
  * and lazy-script group metadata in one pass.
  *
- * The returned structures intentionally preserve both the flat asset list used by
- * asset processing and the grouped lazy-trigger data used later during render output.
+ * @remarks
+ * Explicit stylesheet declarations are collected first across the graph. Inferred
+ * stylesheets are read from component identity afterward and skipped when the same
+ * resolved path already has an explicit entry. The returned structures preserve both
+ * the flat asset list used by asset processing and the grouped lazy-trigger data used
+ * later during render output.
  */
 export declare function collectComponentDependencies(options: CollectComponentDependenciesOptions): CollectedComponentDependencies;
 export {};

package/src/route-renderer/page-loading/component-dependency-collection.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { assertEcoDeclaredComponent } from '../../eco/eco-declared-component.js';
 import { getComponentIdentity } from '../../eco/component-identity.js';
+import { getInferredStylesheets } from '../../eco/discovered-dependencies.js';
 import { AssetFactory } from '../../services/assets/asset-processing-service/index.js';
 import { extractEcopagesVirtualImports } from './ecopages-virtual-imports.js';
 import { collectDeclaredAssetEntries } from './declared-asset-collection.js';
@@ -27,20 +28,27 @@ function pushUniqueDependency(keys, key, dependencies, dependency) {
     return true;
 }
 function resolveDependencyPath(componentDir, pathUrl) {
-    return path.join(componentDir, pathUrl);
+    return path.isAbsolute(pathUrl) ? pathUrl : path.join(componentDir, pathUrl);
 }
 /**
  * Walks component dependency trees and collects declared assets, module declarations,
  * and lazy-script group metadata in one pass.
  *
- * The returned structures intentionally preserve both the flat asset list used by
- * asset processing and the grouped lazy-trigger data used later during render output.
+ * @remarks
+ * Explicit stylesheet declarations are collected first across the graph. Inferred
+ * stylesheets are read from component identity afterward and skipped when the same
+ * resolved path already has an explicit entry. The returned structures preserve both
+ * the flat asset list used by asset processing and the grouped lazy-trigger data used
+ * later during render output.
  */
 export function collectComponentDependencies(options) {
     const { components, integrationName, resolveLazyScripts, createEcopagesJsxLazyEntryName, isEcopagesJsxIntegration, errors, } = options;
     const dependencies = [];
     const lazyScriptsByConfig = new Map();
     const lazyDependencyKeys = new Set();
+    const visited = new Set();
+    const inferredStyles = [];
+    const explicitStylePaths = new Set();
     for (const component of components) {
         if (!component)
             continue;
@@ -54,13 +62,22 @@ export function collectComponentDependencies(options) {
          * Recursively visits one component config and its declared child dependencies.
          */
         const collect = (config) => {
-            if (!config)
+            if (!config || visited.has(config))
                 return;
+            visited.add(config);
             const file = getComponentIdentity(config)?.file;
             if (!file)
                 return;
             const dir = path.dirname(file);
             const dependenciesConfig = config.dependencies;
+            const explicitStyles = dependenciesConfig?.stylesheets ?? [];
+            for (const style of explicitStyles) {
+                const src = typeof style === 'string' ? style : style.src;
+                if (src)
+                    explicitStylePaths.add(resolveDependencyPath(dir, src));
+            }
+            for (const src of getInferredStylesheets(config))
+                inferredStyles.push({ dir, src });
             const registerLazyScript = ({ lazy, lazyKey, fallbackUrl, }) => {
                 let grouped = lazyScriptsByConfig.get(config);
                 if (!grouped) {
@@ -73,7 +90,7 @@ export function collectComponentDependencies(options) {
                 grouped.set(triggerKey, existing);
             };
             collectDeclaredAssetEntries({
-                stylesheetEntries: dependenciesConfig?.stylesheets ?? [],
+                stylesheetEntries: explicitStyles,
                 scriptEntries: dependenciesConfig?.scripts ?? [],
                 componentDir: dir,
                 dependencies,
@@ -125,6 +142,13 @@ export function collectComponentDependencies(options) {
             });
         }));
     }
+    for (const { dir, src } of inferredStyles) {
+        const filepath = resolveDependencyPath(dir, src);
+        if (explicitStylePaths.has(filepath))
+            continue;
+        explicitStylePaths.add(filepath);
+        dependencies.push(AssetFactory.createFileStylesheet({ filepath, position: 'head', attributes: { rel: 'stylesheet' } }));
+    }
     return {
         dependencies,
         lazyScriptsByConfig,

package/src/route-renderer/page-loading/file-scoped-dependency-components.d.ts

@@ -21,12 +21,21 @@ export declare function collectFileScopedDependencyComponents(options: {
     integrationName: string;
     dependencies: EcoComponentDependencies;
 }): Array<EcoComponent | Partial<EcoComponent>>;
+/**
+ * Expands a page dependency result into collector roots, retaining each contribution's owner.
+ */
+export declare function collectPageDependencyComponents(options: {
+    result: PageDependenciesResult;
+    fallbackOwnerFile: string;
+    integrationName: string;
+}): Array<EcoComponent | Partial<EcoComponent>>;
 export type CollectComponentConfigFilePathsOptions = {
     additionalPaths?: ReadonlyArray<string>;
     includeLayouts?: boolean;
+    includeStylesheets?: boolean;
 };
 /**
- * Walks component configs and collects every resolved identity file path.
+ * Walks component configs and collects identity files, stylesheets, and discovered barrel hops.
  */
 export declare function collectComponentConfigFilePaths(components: ReadonlyArray<EcoComponent | Partial<EcoComponent> | undefined>, options?: CollectComponentConfigFilePathsOptions): Set<string>;
 /**
@@ -39,4 +48,5 @@ export declare function collectDependencyWatchPaths(ownerFile: string, component
 export declare function splitPageDependenciesResult(result: PageDependenciesResult): {
     dependencies: EcoComponentDependencies;
     ownerFile?: string;
+    contributions?: PageDependenciesResult['contributions'];
 };

package/src/route-renderer/page-loading/file-scoped-dependency-components.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import { rapidhash } from '../../utils/hash.js';
 import { bindComponentIdentity, getComponentIdentity } from '../../eco/component-identity.js';
+import { getDiscoveredWatchFiles, getInferredStylesheets } from '../../eco/discovered-dependencies.js';
+import { listFileOwnedDependencyContributions } from '../../eco/page-dependency-contributions.js';
 /**
  * Attaches canonical file-backed identity to one component config.
  */
@@ -43,7 +45,22 @@ export function collectFileScopedDependencyComponents(options) {
     return components;
 }
 /**
- * Walks component configs and collects every resolved identity file path.
+ * Expands a page dependency result into collector roots, retaining each contribution's owner.
+ */
+export function collectPageDependencyComponents(options) {
+    const components = [];
+    for (const contribution of listFileOwnedDependencyContributions(options.result)) {
+        const { ownerFile, ...dependencies } = contribution;
+        components.push(...collectFileScopedDependencyComponents({
+            ownerFile: ownerFile ?? options.fallbackOwnerFile,
+            integrationName: options.integrationName,
+            dependencies,
+        }));
+    }
+    return components;
+}
+/**
+ * Walks component configs and collects identity files, stylesheets, and discovered barrel hops.
  */
 export function collectComponentConfigFilePaths(components, options) {
     const files = new Set();
@@ -60,11 +77,24 @@ export function collectComponentConfigFilePaths(components, options) {
             return;
         }
         const resolved = path.resolve(file);
-        if (visited.has(resolved)) {
+        if (visited.has(config)) {
             return;
         }
-        visited.add(resolved);
+        visited.add(config);
         files.add(resolved);
+        for (const style of options?.includeStylesheets ? (config.dependencies?.stylesheets ?? []) : []) {
+            const src = typeof style === 'string' ? style : style.src;
+            if (src)
+                files.add(path.resolve(path.dirname(resolved), src));
+        }
+        if (options?.includeStylesheets) {
+            for (const src of getInferredStylesheets(config)) {
+                files.add(path.resolve(path.dirname(resolved), src));
+            }
+        }
+        for (const watchFile of getDiscoveredWatchFiles(config)) {
+            files.add(path.resolve(watchFile));
+        }
         for (const dependency of config.dependencies?.components ?? []) {
             visit(dependency?.config);
         }
@@ -83,12 +113,16 @@ export function collectComponentConfigFilePaths(components, options) {
  * Collects source files that should invalidate a per-instance browser graph entry.
  */
 export function collectDependencyWatchPaths(ownerFile, components) {
-    return Array.from(collectComponentConfigFilePaths(components, { additionalPaths: [ownerFile] }));
+    return Array.from(collectComponentConfigFilePaths(components, { additionalPaths: [ownerFile], includeStylesheets: true }));
 }
 /**
  * Separates optional owner metadata from a resolved page dependency bag.
  */
 export function splitPageDependenciesResult(result) {
-    const { ownerFile, ...dependencies } = result;
-    return { dependencies, ownerFile };
+    const { ownerFile, contributions, ...dependencies } = result;
+    return {
+        dependencies,
+        ownerFile,
+        ...(contributions ? { contributions } : {}),
+    };
 }

package/src/route-renderer/page-loading/resolved-page-dependencies.d.ts

@@ -1,11 +1,10 @@
 import type { EcoComponent, PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../types/public-types.js';
-import { collectFileScopedDependencyComponents } from './file-scoped-dependency-components.js';
 export type ResolvedPageDependencies = {
     ownerFile: string;
     components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     contribution?: PageBrowserGraphContribution;
 };
-export type ResolvePageDependenciesContribution = (dependencies: Parameters<typeof collectFileScopedDependencyComponents>[0]['dependencies'], ownerFile: string, components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>) => Promise<PageBrowserGraphContribution | undefined>;
+export type ResolvePageDependenciesContribution = (components: ReadonlyArray<EcoComponent | Partial<EcoComponent>>, ownerFile: string) => Promise<PageBrowserGraphContribution | undefined>;
 /**
  * Resolves `eco.page().dependencies()` once for one graph contribution context.
  */

package/src/route-renderer/page-loading/resolved-page-dependencies.js

@@ -1,4 +1,5 @@
-import { collectFileScopedDependencyComponents, splitPageDependenciesResult, } from './file-scoped-dependency-components.js';
+import { listFileOwnedDependencyContributions } from '../../eco/page-dependency-contributions.js';
+import { collectPageDependencyComponents } from './file-scoped-dependency-components.js';
 /**
  * Resolves `eco.page().dependencies()` once for one graph contribution context.
  */
@@ -16,12 +17,12 @@ export async function resolvePageDependenciesFromContext(context, integrationNam
     if (!dependenciesResult) {
         return undefined;
     }
-    const { dependencies, ownerFile } = splitPageDependenciesResult(dependenciesResult);
-    const resolvedOwnerFile = ownerFile ?? context.file;
-    const components = collectFileScopedDependencyComponents({
-        ownerFile: resolvedOwnerFile,
+    const contributions = listFileOwnedDependencyContributions(dependenciesResult);
+    const resolvedOwnerFile = contributions.length === 1 ? (contributions[0]?.ownerFile ?? context.file) : context.file;
+    const components = collectPageDependencyComponents({
+        result: dependenciesResult,
+        fallbackOwnerFile: context.file,
         integrationName,
-        dependencies,
     });
     if (components.length === 0) {
         return {
@@ -29,7 +30,7 @@ export async function resolvePageDependenciesFromContext(context, integrationNam
             components,
         };
     }
-    const contribution = await materializeContribution(dependencies, resolvedOwnerFile, components);
+    const contribution = await materializeContribution(components, resolvedOwnerFile);
     return {
         ownerFile: resolvedOwnerFile,
         components,

package/src/services/module-loading/page-module-import.service.d.ts

@@ -16,6 +16,8 @@ interface PageModuleImportBaseOptions {
 export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
     rootDir: string;
     outdir: string;
+    /** Use the server build pipeline even when a development host can load source modules. */
+    forceBuild?: boolean;
     buildExecutor?: BuildExecutor;
     splitting?: boolean;
     externalPackages?: boolean;

package/src/services/module-loading/page-module-import.service.js

@@ -72,7 +72,8 @@ export class PageModuleImportService {
     async importModule(options) {
         const { filePath } = options;
         const fileHash = this.dependencies.hashFile(filePath);
-        const hostModuleLoader = typeof Bun === 'undefined' &&
+        const hostModuleLoader = !options.forceBuild &&
+            typeof Bun === 'undefined' &&
             process.env.NODE_ENV === 'development' &&
             this.dependencies.canLoadSourceModuleFromHost(filePath)
             ? this.dependencies.getHostModuleLoader()

package/src/static-site-generator/README.md

@@ -58,10 +58,12 @@ Integrations may implement:
 - `beforeStaticExport(context)` — runs after unified-graph prebuild, before page rendering
 - `afterStaticExport(context)` — runs in a `finally` block after generation completes
 
-When `appConfig.sitemap.enabled` is true, `sitemap.xml` is written **after** `afterStaticExport` so integration-generated URLs can be listed via `extraUrls`.
+When `appConfig.sitemap.enabled` is true, `sitemap.xml` is written **after** `afterStaticExport` so integration-generated URLs can be listed via `extraUrls`. Development (`ecopages dev`) does not emit this file.
 
 Sitemap eligibility is decided during successful page export (`activeStaticPathnames` plus `robots.index !== false`, fail-closed on metadata errors). `resolveSitemapLocations` then applies `exclude` and appends `extraUrls`.
 
 `StaticExportContext.routes` is the unfiltered static-generation route list. Sitemap filtering is applied separately.
 
 See `StaticExportContext` in `static-export-context.ts`.
+
+User-facing guide: [Sitemap](https://github.com/ecopages/ecopages/blob/main/apps/docs/src/content/docs/core/sitemap.mdx) in the docs app.

package/src/types/public-types.d.ts

@@ -11,7 +11,7 @@ import type { InteractionEventsString as ScriptsInjectorInteractionEventsString
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
 import type { DevTransformBundleContributor } from '../dev/transform-server/types.js';
 export type { EcoPagesAppConfig } from './internal-types.js';
-export type { EcoPageComponent, GetPageDependencies, GetPageDependenciesContext, PageDependenciesResult, } from '../eco/eco.types.js';
+export type { EcoPageComponent, FileOwnedDependencyContribution, GetPageDependencies, GetPageDependenciesContext, PageDependenciesResult, } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
 /**
  * Runtime-agnostic incoming WebSocket frame.