npm - @ecopages/core - Versions diffs - 0.2.0-alpha.1 → 0.2.0-alpha.10 - Mend

@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (323) hide show

package/src/route-renderer/{integration-renderer.js → orchestration/integration-renderer.js} RENAMED Viewed

@@ -1,12 +1,12 @@
-import {} from "../services/asset-processing-service/index.js";
-import { HtmlTransformerService } from "../services/html-transformer.service.js";
-import { invariant } from "../utils/invariant.js";
-import { HttpError } from "../errors/http-error.js";
-import { LocalsAccessError } from "../errors/locals-access-error.js";
-import { DependencyResolverService } from "./dependency-resolver.js";
-import { HtmlPostProcessingService } from "./html-post-processing.service.js";
-import { PageModuleLoaderService } from "./page-module-loader.js";
-import { MarkerGraphResolver } from "./marker-graph-resolver.js";
+import {
+} from "../../services/assets/asset-processing-service/index.js";
+import { HtmlTransformerService } from "../../services/html/html-transformer.service.js";
+import { invariant } from "../../utils/invariant.js";
+import { HttpError } from "../../errors/http-error.js";
+import { LocalsAccessError } from "../../errors/locals-access-error.js";
+import { DependencyResolverService } from "../page-loading/dependency-resolver.js";
+import { PageModuleLoaderService } from "../page-loading/page-module-loader.js";
+import { MarkerGraphResolver } from "../component-graph/marker-graph-resolver.js";
 import { RenderExecutionService } from "./render-execution.service.js";
 import { RenderPreparationService } from "./render-preparation.service.js";
 function createLocalsProxy(filePath) {
@@ -49,7 +49,6 @@ class IntegrationRenderer {
   pageModuleLoaderService;
   markerGraphResolver;
   renderPreparationService;
-  htmlPostProcessingService;
   renderExecutionService;
   DOC_TYPE = "<!DOCTYPE html>";
   setHmrManager(hmrManager) {
@@ -104,7 +103,7 @@ class IntegrationRenderer {
   async prepareViewDependencies(view, layout) {
     const HtmlTemplate = await this.getHtmlTemplate();
     const componentsToResolve = layout ? [HtmlTemplate, layout, view] : [HtmlTemplate, view];
-    const resolvedDependencies = this.htmlPostProcessingService.dedupeProcessedAssets(
+    const resolvedDependencies = this.htmlTransformer.dedupeProcessedAssets(
       await this.resolveDependencies(componentsToResolve)
     );
     this.htmlTransformer.setProcessedDependencies(resolvedDependencies);
@@ -125,7 +124,6 @@ class IntegrationRenderer {
     this.pageModuleLoaderService = new PageModuleLoaderService(appConfig, runtimeOrigin);
     this.markerGraphResolver = new MarkerGraphResolver();
     this.renderPreparationService = new RenderPreparationService(appConfig, assetProcessingService);
-    this.htmlPostProcessingService = new HtmlPostProcessingService();
     this.renderExecutionService = new RenderExecutionService();
   }
   /**
@@ -292,7 +290,7 @@ class IntegrationRenderer {
       }),
       getComponentRenderBoundaryContext: () => this.getComponentRenderBoundaryContext(),
       setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-      dedupeProcessedAssets: (assets) => this.htmlPostProcessingService.dedupeProcessedAssets(assets),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
       createPageLocalsProxy: (filePath) => createLocalsProxy(filePath)
     });
   }
@@ -353,10 +351,12 @@ class IntegrationRenderer {
         componentsToResolve: input.componentsToResolve,
         graphContext: input.graphContext
       }),
-      dedupeProcessedAssets: (assets) => this.htmlPostProcessingService.dedupeProcessedAssets(assets),
+      getDocumentAttributes: (renderOptions) => this.getDocumentAttributes(renderOptions),
+      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
       getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
       setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
-      applyAttributesToFirstBodyElement: (html, attributes) => this.htmlPostProcessingService.applyAttributesToFirstBodyElement(html, attributes),
+      applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
+      applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes),
       transformHtml: async (html) => {
         const response = await this.htmlTransformer.transform(
           new Response(html, {
@@ -369,6 +369,69 @@ class IntegrationRenderer {
       }
     });
   }
+  /**
+   * Captures a render pass as immutable HTML along with the graph context needed
+   * for deferred marker resolution.
+   *
+   * This is the shared entry point for direct `renderToResponse()` flows that
+   * need the same component graph capture semantics as route execution without
+   * going through `prepareRenderOptions()`.
+   */
+  async captureHtmlRender(render) {
+    return this.renderExecutionService.captureHtmlRender(
+      this.name,
+      this.getComponentRenderBoundaryContext(),
+      render
+    );
+  }
+  /**
+   * Finalizes previously captured HTML by resolving deferred markers, merging
+   * any emitted assets, stamping optional attributes, and optionally running the
+   * HTML transformer for full-document flows.
+   */
+  async finalizeCapturedHtmlRender(options) {
+    const finalization = await this.renderExecutionService.finalizeHtmlRender(
+      {
+        html: options.html,
+        graphContext: options.graphContext,
+        componentsToResolve: options.componentsToResolve,
+        componentRootAttributes: options.componentRootAttributes,
+        documentAttributes: options.documentAttributes,
+        mergeAssets: options.mergeAssets ?? !options.partial
+      },
+      {
+        resolveMarkerGraphHtml: (input) => this.resolveMarkerGraphHtml({
+          html: input.html,
+          componentsToResolve: input.componentsToResolve,
+          graphContext: input.graphContext
+        }),
+        dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
+        getProcessedDependencies: () => this.htmlTransformer.getProcessedDependencies(),
+        setProcessedDependencies: (dependencies) => this.htmlTransformer.setProcessedDependencies(dependencies),
+        applyAttributesToHtmlElement: (html, attributes) => this.htmlTransformer.applyAttributesToHtmlElement(html, attributes),
+        applyAttributesToFirstBodyElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstBodyElement(html, attributes)
+      }
+    );
+    const shouldTransform = options.transformHtml ?? !options.partial;
+    if (!shouldTransform) {
+      return finalization.html;
+    }
+    const transformedResponse = await this.htmlTransformer.transform(
+      new Response(finalization.html, {
+        headers: { "Content-Type": "text/html" }
+      })
+    );
+    return await transformedResponse.text();
+  }
+  /**
+   * Returns document-level attributes to stamp onto the rendered `<html>` tag.
+   *
+   * Integrations can override this to expose explicit document ownership or
+   * other runtime coordination markers without relying on script sniffing.
+   */
+  getDocumentAttributes(_renderOptions) {
+    return void 0;
+  }
   /**
    * Resolves all `eco-marker` placeholders in rendered HTML using integration
    * dispatch and bottom-up graph execution.
@@ -399,7 +462,7 @@ class IntegrationRenderer {
       componentsToResolve: options.componentsToResolve,
       graphContext: options.graphContext,
       resolveRenderer: (integrationName) => this.getIntegrationRendererForName(integrationName, integrationRendererCache),
-      applyAttributesToFirstElement: (html, attributes) => this.htmlPostProcessingService.applyAttributesToFirstElement(html, attributes)
+      applyAttributesToFirstElement: (html, attributes) => this.htmlTransformer.applyAttributesToFirstElement(html, attributes)
     });
   }
   /**

package/src/route-renderer/{render-execution.service.d.ts → orchestration/render-execution.service.d.ts} RENAMED Viewed

@@ -1,7 +1,7 @@
-import { type ComponentRenderBoundaryContext } from '../eco/component-render-context.js';
-import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../public-types.js';
-import type { ProcessedAsset } from '../services/asset-processing-service/index.js';
-import type { MarkerGraphContext } from './marker-graph-resolver.js';
+import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
+import type { EcoComponent, IntegrationRendererRenderOptions, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { MarkerGraphContext } from '../component-graph/marker-graph-resolver.js';
 /**
  * Serializable graph context merged from render-time captured references and
  * optional explicit page-module graph metadata.
@@ -10,10 +10,23 @@ export type RenderExecutionGraphContext = {
     propsByRef?: Record<string, Record<string, unknown>>;
     slotChildrenByRef?: MarkerGraphContext['slotChildrenByRef'];
 };
+export interface CapturedHtmlRenderResult {
+    html: string;
+    graphContext: RenderExecutionGraphContext;
+}
+export interface FinalizeHtmlRenderOptions {
+    html: string;
+    graphContext: RenderExecutionGraphContext;
+    componentsToResolve: EcoComponent[];
+    componentRootAttributes?: Record<string, string>;
+    documentAttributes?: Record<string, string>;
+    mergeAssets?: boolean;
+}
 export interface RenderExecutionCallbacks<C> {
     prepareRenderOptions(options: RouteRendererOptions): Promise<IntegrationRendererRenderOptions<C>>;
     render(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     getComponentRenderBoundaryContext(): ComponentRenderBoundaryContext;
+    getDocumentAttributes(renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
     resolveMarkerGraphHtml(input: {
         html: string;
         componentsToResolve: EcoComponent[];
@@ -25,9 +38,25 @@ export interface RenderExecutionCallbacks<C> {
     dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
     getProcessedDependencies(): ProcessedAsset[];
     setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
     applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
     transformHtml(html: string): Promise<RouteRendererBody>;
 }
+export interface FinalizeHtmlRenderCallbacks {
+    resolveMarkerGraphHtml(input: {
+        html: string;
+        componentsToResolve: EcoComponent[];
+        graphContext: RenderExecutionGraphContext;
+    }): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+    getProcessedDependencies(): ProcessedAsset[];
+    setProcessedDependencies(dependencies: ProcessedAsset[]): void;
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+}
 /**
  * Executes the main post-preparation rendering flow for integration renderers.
  *
@@ -37,6 +66,7 @@ export interface RenderExecutionCallbacks<C> {
  * transformation into a response body stream.
  */
 export declare class RenderExecutionService {
+    captureHtmlRender(currentIntegrationName: string, boundaryContext: ComponentRenderBoundaryContext, render: () => Promise<RouteRendererBody>): Promise<CapturedHtmlRenderResult>;
     /**
      * Executes one integration render pass and returns the final route render
      * result.
@@ -56,7 +86,11 @@ export declare class RenderExecutionService {
      * @param explicitGraphContext Optional page-module graph metadata.
      * @returns Merged graph context used during marker resolution.
      */
-    private mergeGraphContext;
+    mergeGraphContext(capturedGraphContext: RenderExecutionGraphContext, explicitGraphContext?: RenderExecutionGraphContext): RenderExecutionGraphContext;
+    finalizeHtmlRender(options: FinalizeHtmlRenderOptions, callbacks: FinalizeHtmlRenderCallbacks): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
     /**
      * Returns the component set that participates in marker graph resolution for a
      * render pass.

package/src/route-renderer/{render-execution.service.js → orchestration/render-execution.service.js} RENAMED Viewed

@@ -1,7 +1,20 @@
 import {
   runWithComponentRenderContext
-} from "../eco/component-render-context.js";
+} from "../../eco/component-render-context.js";
 class RenderExecutionService {
+  async captureHtmlRender(currentIntegrationName, boundaryContext, render) {
+    const renderExecution = await runWithComponentRenderContext(
+      {
+        currentIntegration: currentIntegrationName,
+        boundaryContext
+      },
+      render
+    );
+    return {
+      html: await new Response(renderExecution.value).text(),
+      graphContext: renderExecution.graphContext
+    };
+  }
   /**
    * Executes one integration render pass and returns the final route render
    * result.
@@ -15,40 +28,27 @@ class RenderExecutionService {
   async execute(options, currentIntegrationName, callbacks) {
     const renderOptions = await callbacks.prepareRenderOptions(options);
     const shouldApplyComponentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0;
-    const renderExecution = await runWithComponentRenderContext(
-      {
-        currentIntegration: currentIntegrationName,
-        boundaryContext: callbacks.getComponentRenderBoundaryContext()
-      },
+    const renderExecution = await this.captureHtmlRender(
+      currentIntegrationName,
+      callbacks.getComponentRenderBoundaryContext(),
       async () => callbacks.render(renderOptions)
     );
-    let renderedHtml = await new Response(renderExecution.value).text();
     const componentGraphContext = this.mergeGraphContext(
       renderExecution.graphContext,
       renderOptions.componentGraphContext
     );
-    if (renderedHtml.includes("<eco-marker")) {
-      const markerResolution = await callbacks.resolveMarkerGraphHtml({
-        html: renderedHtml,
+    const finalization = await this.finalizeHtmlRender(
+      {
+        html: renderExecution.html,
+        graphContext: componentGraphContext,
         componentsToResolve: this.getComponentsToResolve(renderOptions),
-        graphContext: componentGraphContext
-      });
-      renderedHtml = markerResolution.html;
-      if (markerResolution.assets.length > 0) {
-        const mergedDependencies = callbacks.dedupeProcessedAssets([
-          ...callbacks.getProcessedDependencies(),
-          ...markerResolution.assets
-        ]);
-        callbacks.setProcessedDependencies(mergedDependencies);
-      }
-    }
-    if (shouldApplyComponentRootAttributes) {
-      renderedHtml = callbacks.applyAttributesToFirstBodyElement(
-        renderedHtml,
-        renderOptions.componentRender?.rootAttributes
-      );
-    }
-    const body = await callbacks.transformHtml(renderedHtml);
+        componentRootAttributes: shouldApplyComponentRootAttributes ? renderOptions.componentRender?.rootAttributes : void 0,
+        documentAttributes: callbacks.getDocumentAttributes(renderOptions),
+        mergeAssets: true
+      },
+      callbacks
+    );
+    const body = await callbacks.transformHtml(finalization.html);
     return {
       body,
       cacheStrategy: renderOptions.cacheStrategy
@@ -74,6 +74,36 @@ class RenderExecutionService {
       }
     };
   }
+  async finalizeHtmlRender(options, callbacks) {
+    let renderedHtml = options.html;
+    let markerAssets = [];
+    if (renderedHtml.includes("<eco-marker")) {
+      const markerResolution = await callbacks.resolveMarkerGraphHtml({
+        html: renderedHtml,
+        componentsToResolve: options.componentsToResolve,
+        graphContext: options.graphContext
+      });
+      renderedHtml = markerResolution.html;
+      markerAssets = markerResolution.assets;
+      if (options.mergeAssets !== false && markerResolution.assets.length > 0) {
+        const mergedDependencies = callbacks.dedupeProcessedAssets([
+          ...callbacks.getProcessedDependencies(),
+          ...markerResolution.assets
+        ]);
+        callbacks.setProcessedDependencies(mergedDependencies);
+      }
+    }
+    if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
+      renderedHtml = callbacks.applyAttributesToFirstBodyElement(renderedHtml, options.componentRootAttributes);
+    }
+    if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
+      renderedHtml = callbacks.applyAttributesToHtmlElement(renderedHtml, options.documentAttributes);
+    }
+    return {
+      html: renderedHtml,
+      assets: markerAssets
+    };
+  }
   /**
    * Returns the component set that participates in marker graph resolution for a
    * render pass.

package/src/route-renderer/{render-preparation.service.d.ts → orchestration/render-preparation.service.d.ts} RENAMED Viewed

@@ -1,7 +1,7 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererOptions } from '../public-types.js';
-import { type AssetProcessingService, type ProcessedAsset } from '../services/asset-processing-service/index.js';
-import { type ComponentRenderBoundaryContext } from '../eco/component-render-context.js';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, EcoPagesElement, GetMetadata, GetStaticProps, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererOptions } from '../../public-types.js';
+import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import { type ComponentRenderBoundaryContext } from '../../eco/component-render-context.js';
 type ResolvedPageModule = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     getStaticProps?: GetStaticProps<Record<string, unknown>>;
@@ -49,6 +49,13 @@ export interface RenderPreparationCallbacks {
 export declare class RenderPreparationService {
     private appConfig;
     private assetProcessingService;
+    /**
+     * Creates the render-preparation orchestrator for one app instance.
+     *
+     * @remarks
+     * The service is app-scoped because it depends on finalized config defaults and
+     * the app-owned asset-processing pipeline while remaining renderer-agnostic.
+     */
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
     /**
      * Builds the final render options object used by the integration-specific
@@ -108,5 +115,7 @@ export declare class RenderPreparationService {
      * @returns Processed assets that should be merged into the final dependency set.
      */
     private buildGlobalInjectorAssets;
+    private buildEagerSsrLazyAssets;
+    private collectEagerSsrLazyDependencies;
 }
 export {};

package/src/route-renderer/{render-preparation.service.js → orchestration/render-preparation.service.js} RENAMED Viewed

@@ -1,11 +1,22 @@
 import { createRequire } from "node:module";
 import {
   AssetFactory
-} from "../services/asset-processing-service/index.js";
-import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../eco/global-injector-map.js";
-import { runWithComponentRenderContext } from "../eco/component-render-context.js";
+} from "../../services/assets/asset-processing-service/index.js";
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../../eco/global-injector-map.js";
+import {
+  runWithComponentRenderContext
+} from "../../eco/component-render-context.js";
 const coreRequire = createRequire(import.meta.url);
 class RenderPreparationService {
+  appConfig;
+  assetProcessingService;
+  /**
+   * Creates the render-preparation orchestrator for one app instance.
+   *
+   * @remarks
+   * The service is app-scoped because it depends on finalized config defaults and
+   * the app-owned asset-processing pipeline while remaining renderer-agnostic.
+   */
   constructor(appConfig, assetProcessingService) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
@@ -56,6 +67,10 @@ class RenderPreparationService {
       const globalAssets = await this.buildGlobalInjectorAssets(triggers, currentIntegrationName);
       allDependencies.push(...globalAssets);
     }
+    const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, currentIntegrationName);
+    if (eagerSsrLazyAssets.length > 0) {
+      allDependencies.push(...eagerSsrLazyAssets);
+    }
     callbacks.setProcessedDependencies(callbacks.dedupeProcessedAssets(allDependencies));
     const pageProps = {
       ...props,
@@ -237,6 +252,80 @@ class RenderPreparationService {
       currentIntegrationName
     );
   }
+  async buildEagerSsrLazyAssets(components, currentIntegrationName) {
+    const dependencies = this.collectEagerSsrLazyDependencies(components);
+    if (dependencies.length === 0) {
+      return [];
+    }
+    return this.assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+  }
+  collectEagerSsrLazyDependencies(components) {
+    const dependencies = [];
+    const visitedConfigs = /* @__PURE__ */ new Set();
+    const seenKeys = /* @__PURE__ */ new Set();
+    const normalizeAttributes = (attributes) => ({
+      type: "module",
+      defer: "",
+      ...attributes ?? {}
+    });
+    const collect = (config) => {
+      if (!config || visitedConfigs.has(config)) {
+        return;
+      }
+      visitedConfigs.add(config);
+      const componentFile = config.__eco?.file;
+      if (componentFile) {
+        const componentDir = coreRequire("node: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 key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
+            if (seenKeys.has(key2)) {
+              continue;
+            }
+            seenKeys.add(key2);
+            dependencies.push(
+              AssetFactory.createContentScript({
+                position: "head",
+                content: script.content,
+                attributes
+              })
+            );
+            continue;
+          }
+          if (!script.src) {
+            continue;
+          }
+          const resolvedPath = coreRequire("node: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
+            })
+          );
+        }
+      }
+      if (config.layout?.config) {
+        collect(config.layout.config);
+      }
+      for (const nestedComponent of config.dependencies?.components ?? []) {
+        collect(nestedComponent?.config);
+      }
+    };
+    for (const component of components) {
+      collect(component.config);
+    }
+    return dependencies;
+  }
 }
 export {
   RenderPreparationService

package/src/route-renderer/{dependency-resolver.d.ts → page-loading/dependency-resolver.d.ts} RENAMED Viewed

@@ -1,6 +1,6 @@
-import type { EcoComponent } from '../public-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { AssetProcessingService, ProcessedAsset } from '../services/asset-processing-service/index.js';
+import type { EcoComponent } from '../../public-types.js';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 export declare const DEPENDENCY_ERRORS: {
     readonly INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content";
     readonly INVALID_SCRIPT_ENTRY: "Invalid script dependency entry: expected src or content";
@@ -9,7 +9,18 @@ export declare const DEPENDENCY_ERRORS: {
 export declare class DependencyResolverService {
     private appConfig;
     private assetProcessingService;
+    /**
+     * Creates the dependency resolver used by route and component rendering.
+     *
+     * @remarks
+     * The resolver stays intentionally separate from HTML rendering so component
+     * dependency collection, lazy trigger grouping, and processed-asset generation
+     * can evolve without changing renderer implementations.
+     */
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    /**
+     * Resolves one dependency path relative to the component that declared it.
+     */
     resolveDependencyPath(componentDir: string, pathUrl: string): string;
     /**
      * Maps lazy script source entries to deterministic fallback public URLs
@@ -20,5 +31,5 @@ export declare class DependencyResolverService {
      * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
      * Lazy dependencies are always resolved into global-injector trigger maps.
      */
-    processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[], integrationName: string): Promise<ProcessedAsset[]>;
+    processComponentDependencies(components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>, integrationName: string): Promise<ProcessedAsset[]>;
 }

package/src/route-renderer/{dependency-resolver.js → page-loading/dependency-resolver.js} RENAMED Viewed

@@ -1,8 +1,8 @@
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { rapidhash } from "../utils/hash.js";
-import { AssetFactory } from "../services/asset-processing-service/index.js";
-import { normalizeModuleDeclarations } from "../eco/module-dependencies.js";
+import { rapidhash } from "../../utils/hash.js";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { normalizeModuleDeclarations } from "../../eco/module-dependencies.js";
 import { parseSync } from "oxc-parser";
 const DEPENDENCY_ERRORS = {
   INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content",
@@ -139,10 +139,23 @@ function buildResolvedLazyTriggers(config, groups) {
   return [{ triggerId, rules }];
 }
 class DependencyResolverService {
+  appConfig;
+  assetProcessingService;
+  /**
+   * Creates the dependency resolver used by route and component rendering.
+   *
+   * @remarks
+   * The resolver stays intentionally separate from HTML rendering so component
+   * dependency collection, lazy trigger grouping, and processed-asset generation
+   * can evolve without changing renderer implementations.
+   */
   constructor(appConfig, assetProcessingService) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
   }
+  /**
+   * Resolves one dependency path relative to the component that declared it.
+   */
   resolveDependencyPath(componentDir, pathUrl) {
     return resolveDependencyPath(componentDir, pathUrl);
   }
@@ -163,6 +176,7 @@ class DependencyResolverService {
     const lazyScriptsByConfig = /* @__PURE__ */ new Map();
     const lazyDependencyKeys = /* @__PURE__ */ new Set();
     for (const component of components) {
+      if (!component) continue;
       const componentFile = component.config?.__eco?.file;
       if (!componentFile) continue;
       const stylesheetDependencyKeys = /* @__PURE__ */ new Set();
@@ -357,7 +371,7 @@ class DependencyResolverService {
         }
         if (dependenciesConfig?.components) {
           for (const nestedComponent of dependenciesConfig.components) {
-            if (nestedComponent.config) {
+            if (nestedComponent?.config) {
               collect(nestedComponent.config);
             }
           }