@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.26

package/src/route-renderer/orchestration/route-shell-composer.service.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, HtmlTemplateProps, PageMetadataProps } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { RenderToResponseContext } from './integration-renderer.js';
+export interface RouteShellComposerCallbacks {
+    hasForeignBoundaryDescendants(component: EcoComponent): boolean;
+    createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
+    renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+    getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+    resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+    appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+    finalizeResolvedHtml(options: {
+        html: string;
+        partial?: boolean;
+        componentRootAttributes?: Record<string, string>;
+        documentAttributes?: Record<string, string>;
+        transformHtml?: boolean;
+    }): Promise<string>;
+    docType: string;
+}
+export declare class RouteShellComposer {
+    renderPartialViewResponse<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        renderInline?: () => Promise<BodyInit>;
+        transformHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderViewWithDocumentShell<P>(input: {
+        view: EcoComponent<P>;
+        props: P;
+        ctx: RenderToResponseContext;
+        layout?: EcoComponent;
+    }, callbacks: RouteShellComposerCallbacks): Promise<Response>;
+    renderPageWithDocumentShell(input: {
+        page: {
+            component: EcoComponent;
+            props: Record<string, unknown>;
+        };
+        layout?: {
+            component: EcoComponent;
+            props?: Record<string, unknown>;
+        };
+        htmlTemplate: EcoComponent;
+        metadata: PageMetadataProps;
+        pageProps: Record<string, unknown>;
+        documentProps?: Record<string, unknown>;
+        transformDocumentHtml?: (html: string) => string;
+    }, callbacks: RouteShellComposerCallbacks): Promise<string>;
+}

package/src/route-renderer/orchestration/route-shell-composer.service.js

@@ -0,0 +1,81 @@
+class RouteShellComposer {
+  async renderPartialViewResponse(input, callbacks) {
+    if (input.renderInline && !callbacks.hasForeignBoundaryDescendants(input.view)) {
+      return callbacks.createHtmlResponse(await input.renderInline(), input.ctx);
+    }
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: input.props ?? {},
+      integrationContext: { rendererCache }
+    });
+    const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderViewWithDocumentShell(input, callbacks) {
+    const normalizedProps = input.props ?? {};
+    if (input.ctx.partial) {
+      return this.renderPartialViewResponse(input, callbacks);
+    }
+    await callbacks.prepareViewDependencies(input.view, input.layout);
+    const HtmlTemplate = await callbacks.getHtmlTemplate();
+    const metadata = await callbacks.resolveViewMetadata(input.view, input.props);
+    const rendererCache = /* @__PURE__ */ new Map();
+    const viewRender = await callbacks.renderComponentBoundary({
+      component: input.view,
+      props: normalizedProps,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout,
+      props: {},
+      children: viewRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: HtmlTemplate,
+      props: {
+        metadata,
+        pageProps: normalizedProps
+      },
+      children: layoutRender?.html ?? viewRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
+    const html = await callbacks.finalizeResolvedHtml({
+      html: `${callbacks.docType}${documentRender.html}`,
+      partial: false
+    });
+    return callbacks.createHtmlResponse(html, input.ctx);
+  }
+  async renderPageWithDocumentShell(input, callbacks) {
+    const rendererCache = /* @__PURE__ */ new Map();
+    const pageRender = await callbacks.renderComponentBoundary({
+      component: input.page.component,
+      props: input.page.props,
+      integrationContext: { rendererCache }
+    });
+    const layoutRender = input.layout ? await callbacks.renderComponentBoundary({
+      component: input.layout.component,
+      props: input.layout.props ?? {},
+      children: pageRender.html,
+      integrationContext: { rendererCache }
+    }) : void 0;
+    const documentRender = await callbacks.renderComponentBoundary({
+      component: input.htmlTemplate,
+      props: {
+        metadata: input.metadata,
+        pageProps: input.pageProps,
+        ...input.documentProps ?? {}
+      },
+      children: layoutRender?.html ?? pageRender.html,
+      integrationContext: { rendererCache }
+    });
+    callbacks.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
+    const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(documentRender.html) : documentRender.html;
+    return `${callbacks.docType}${documentHtml}`;
+  }
+}
+export {
+  RouteShellComposer
+};

package/src/route-renderer/orchestration/template-serialization.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal template-result shape that core can serialize generically.
+ *
+ * @remarks
+ * Core intentionally models only the transport shape used during deferred
+ * cross-integration child passing: alternating static string segments plus
+ * interpolated runtime values. Concrete runtime markers that identify a given
+ * framework's template payload must stay outside core and be registered by the
+ * owning integration package.
+ */
+export type SerializableTemplateShape = {
+    strings: readonly string[];
+    values?: readonly unknown[];
+};
+/**
+ * Integration-owned adapter that teaches core how to serialize one deferred
+ * template payload shape.
+ *
+ * @remarks
+ * The separation here is intentional: core owns the HTML serialization logic,
+ * but integrations own runtime-shape detection. That keeps package-specific
+ * markers such as framework template sentinels out of core while still letting
+ * deferred children round-trip through mixed renderer boundaries.
+ */
+export type DeferredTemplateSerializer<TTemplate extends SerializableTemplateShape = SerializableTemplateShape> = {
+    matches(value: unknown): value is TTemplate;
+    serialize(template: TTemplate, serializeValue: (value: unknown) => string | undefined): string;
+};
+/**
+ * Serializes a generic template shape into HTML.
+ *
+ * @remarks
+ * This handles only HTML reconstruction semantics: quoted attribute values,
+ * boolean attributes, and omission of client-only event or property bindings.
+ * It does not decide whether an arbitrary value belongs to a framework-specific
+ * template runtime; integrations must make that decision before delegating here.
+ */
+export declare function serializeTemplateShape(template: SerializableTemplateShape, serializeValue: (value: unknown) => string | undefined): string;

package/src/route-renderer/orchestration/template-serialization.js

@@ -0,0 +1,45 @@
+import { escapeHtmlAttribute } from "../../utils/html-escaping.js";
+const ATTRIBUTE_TAIL_PATTERN = /(\s+)([@.?!]?)([^\s"'<>/=`@.?!]+)=$/;
+function getSerializableTemplateAttribute(stringPart) {
+  const match = ATTRIBUTE_TAIL_PATTERN.exec(stringPart);
+  if (!match) return void 0;
+  return {
+    leading: stringPart.slice(0, match.index),
+    whitespace: match[1],
+    prefix: match[2],
+    name: match[3]
+  };
+}
+function serializeTemplateShape(template, serializeValue) {
+  const values = template.values ?? [];
+  let html = "";
+  for (let index = 0; index < values.length; index += 1) {
+    const stringPart = template.strings[index] ?? "";
+    const serializedValue = serializeValue(values[index]);
+    const attribute = getSerializableTemplateAttribute(stringPart);
+    if (!attribute) {
+      html += stringPart;
+      html += serializedValue ?? "";
+      continue;
+    }
+    html += attribute.leading;
+    if (attribute.prefix === "@" || attribute.prefix === "!" || attribute.prefix === ".") {
+      continue;
+    }
+    if (attribute.prefix === "?") {
+      if (serializedValue) {
+        html += `${attribute.whitespace}${attribute.name}`;
+      }
+      continue;
+    }
+    if (serializedValue === void 0) {
+      continue;
+    }
+    html += `${attribute.whitespace}${attribute.name}="${escapeHtmlAttribute(serializedValue)}"`;
+  }
+  html += template.strings[values.length] ?? "";
+  return html;
+}
+export {
+  serializeTemplateShape
+};

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

@@ -0,0 +1,37 @@
+import type { EcoComponent } from '../../types/public-types.js';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+import { type LazyGroup } from './lazy-entry-collection.js';
+/**
+ * Aggregated dependency output for one dependency-collection pass.
+ */
+export type CollectedComponentDependencies = {
+    /**
+     * Flat asset declarations ready for downstream processing.
+     */
+    dependencies: AssetDefinition[];
+    /**
+     * Lazy script groups keyed by component config and trigger key.
+     */
+    lazyScriptsByConfig: Map<NonNullable<EcoComponent['config']>, Map<string, LazyGroup>>;
+};
+type CollectComponentDependenciesOptions = {
+    components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>;
+    integrationName: string;
+    resolveLazyScripts: (componentDir: string, scripts: string[]) => string;
+    createEcopagesJsxLazyEntryName: (integrationName: string, key: string) => string;
+    isEcopagesJsxIntegration: (integrationName: string) => boolean;
+    errors: {
+        invalidStylesheetEntry: string;
+        invalidScriptEntry: string;
+        lazyScriptMissingSrc: string;
+    };
+};
+/**
+ * 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.
+ */
+export declare function collectComponentDependencies(options: CollectComponentDependenciesOptions): CollectedComponentDependencies;
+export {};

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

@@ -0,0 +1,125 @@
+import path from "node:path";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { extractEcopagesVirtualImports } from "./ecopages-virtual-imports.js";
+import { collectDeclaredAssetEntries } from "./declared-asset-collection.js";
+import { getLazyTriggerKey } from "./lazy-trigger-planning.js";
+import { collectLazyScriptEntries } from "./lazy-entry-collection.js";
+import {
+  createModuleScriptName,
+  createNamedImportModuleSource,
+  createNamespaceImportModuleSource
+} from "./module-declaration-scripts.js";
+import { collectModuleDeclarations } from "./module-declaration-aggregation.js";
+const MODULE_SCRIPT_ATTRIBUTES = {
+  type: "module",
+  defer: ""
+};
+function createModuleScriptAttributes(attributes) {
+  return {
+    ...MODULE_SCRIPT_ATTRIBUTES,
+    ...attributes
+  };
+}
+function pushUniqueDependency(keys, key, dependencies, dependency) {
+  if (keys.has(key)) {
+    return false;
+  }
+  keys.add(key);
+  dependencies.push(dependency);
+  return true;
+}
+function resolveDependencyPath(componentDir, pathUrl) {
+  return path.join(componentDir, pathUrl);
+}
+function collectComponentDependencies(options) {
+  const { components, integrationName, resolveLazyScripts, createEcopagesJsxLazyEntryName, isEcopagesJsxIntegration, errors } = options;
+  const dependencies = [];
+  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();
+    const scriptDependencyKeys = /* @__PURE__ */ new Set();
+    const modulesMap = /* @__PURE__ */ new Map();
+    const collect = (config) => {
+      if (!config) return;
+      const file = config.__eco?.file;
+      if (!file) return;
+      const dir = path.dirname(file);
+      const dependenciesConfig = config.dependencies;
+      const registerLazyScript = ({
+        lazy,
+        lazyKey,
+        fallbackUrl
+      }) => {
+        let grouped = lazyScriptsByConfig.get(config);
+        if (!grouped) {
+          grouped = /* @__PURE__ */ new Map();
+          lazyScriptsByConfig.set(config, grouped);
+        }
+        const triggerKey = getLazyTriggerKey(lazy);
+        const existing = grouped.get(triggerKey) ?? { lazy, scripts: [] };
+        existing.scripts.push({ lazyKey, fallbackUrl });
+        grouped.set(triggerKey, existing);
+      };
+      collectDeclaredAssetEntries({
+        stylesheetEntries: dependenciesConfig?.stylesheets ?? [],
+        scriptEntries: dependenciesConfig?.scripts ?? [],
+        componentDir: dir,
+        dependencies,
+        stylesheetDependencyKeys,
+        scriptDependencyKeys,
+        resolveDependencyPath,
+        createModuleScriptAttributes,
+        pushUniqueDependency,
+        getInvalidStylesheetEntryMessage: () => errors.invalidStylesheetEntry,
+        getInvalidScriptEntryMessage: () => errors.invalidScriptEntry
+      });
+      collectModuleDeclarations(modulesMap, dependenciesConfig?.modules, extractEcopagesVirtualImports(file));
+      collectLazyScriptEntries({
+        scriptEntries: dependenciesConfig?.scripts ?? [],
+        componentFile: file,
+        componentDir: dir,
+        integrationName,
+        dependencies,
+        lazyDependencyKeys,
+        registerLazyScript,
+        resolveDependencyPath,
+        resolveLazyScripts,
+        createModuleScriptAttributes,
+        createEcopagesJsxLazyEntryName,
+        pushUniqueDependency,
+        getLazyScriptMissingSrcMessage: () => errors.lazyScriptMissingSrc,
+        isEcopagesJsxIntegration
+      });
+      if (dependenciesConfig?.components) {
+        for (const nestedComponent of dependenciesConfig.components) {
+          if (nestedComponent?.config) {
+            collect(nestedComponent.config);
+          }
+        }
+      }
+    };
+    collect(component.config);
+    dependencies.push(
+      ...Array.from(modulesMap.entries()).map(([from, importsSet]) => {
+        const imports = importsSet ? Array.from(importsSet) : void 0;
+        return AssetFactory.createContentScript({
+          position: "head",
+          name: createModuleScriptName(from, imports),
+          content: imports && imports.length > 0 ? createNamedImportModuleSource(from, imports) : createNamespaceImportModuleSource(from),
+          attributes: createModuleScriptAttributes()
+        });
+      })
+    );
+  }
+  return {
+    dependencies,
+    lazyScriptsByConfig
+  };
+}
+export {
+  collectComponentDependencies
+};

package/src/route-renderer/page-loading/declared-asset-collection.d.ts

@@ -0,0 +1,24 @@
+import type { EcoComponentScriptEntry, EcoComponentStylesheetEntry } from '../../types/public-types.js';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+type CollectDeclaredAssetEntriesOptions = {
+    stylesheetEntries: Array<string | EcoComponentStylesheetEntry>;
+    scriptEntries: Array<string | EcoComponentScriptEntry>;
+    componentDir: string;
+    dependencies: AssetDefinition[];
+    stylesheetDependencyKeys: Set<string>;
+    scriptDependencyKeys: Set<string>;
+    resolveDependencyPath: (componentDir: string, pathUrl: string) => string;
+    createModuleScriptAttributes: (attributes?: Record<string, string>) => Record<string, string>;
+    pushUniqueDependency: (keys: Set<string>, key: string, dependencies: AssetDefinition[], dependency: AssetDefinition) => boolean;
+    getInvalidStylesheetEntryMessage: () => string;
+    getInvalidScriptEntryMessage: () => string;
+};
+/**
+ * Normalizes non-lazy stylesheet and script declarations into asset definitions.
+ *
+ * Duplicate declarations are filtered through the provided key sets so callers can
+ * compose this helper into larger recursive collection passes without re-emitting
+ * the same asset multiple times.
+ */
+export declare function collectDeclaredAssetEntries(options: CollectDeclaredAssetEntriesOptions): void;
+export {};

package/src/route-renderer/page-loading/declared-asset-collection.js

@@ -0,0 +1,106 @@
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+function isDependencyEntryObject(entry) {
+  return typeof entry === "object" && entry !== null;
+}
+function getDependencyEntrySrc(entry) {
+  return isDependencyEntryObject(entry) ? entry.src : entry;
+}
+function getDependencyEntryContent(entry) {
+  return isDependencyEntryObject(entry) ? entry.content : void 0;
+}
+function getDependencyEntryAttributes(entry) {
+  return isDependencyEntryObject(entry) ? entry.attributes : void 0;
+}
+function collectDeclaredAssetEntries(options) {
+  const {
+    stylesheetEntries,
+    scriptEntries,
+    componentDir,
+    dependencies,
+    stylesheetDependencyKeys,
+    scriptDependencyKeys,
+    resolveDependencyPath,
+    createModuleScriptAttributes,
+    pushUniqueDependency,
+    getInvalidStylesheetEntryMessage,
+    getInvalidScriptEntryMessage
+  } = options;
+  for (const style of stylesheetEntries) {
+    const content = getDependencyEntryContent(style);
+    const src = getDependencyEntrySrc(style);
+    const attributes = getDependencyEntryAttributes(style);
+    if (content) {
+      const depKey2 = `style:content:${content}:${JSON.stringify(attributes ?? {})}`;
+      pushUniqueDependency(
+        stylesheetDependencyKeys,
+        depKey2,
+        dependencies,
+        AssetFactory.createContentStylesheet({
+          content,
+          position: "head",
+          attributes
+        })
+      );
+      continue;
+    }
+    if (!src) {
+      throw new Error(getInvalidStylesheetEntryMessage());
+    }
+    const resolvedPath = resolveDependencyPath(componentDir, src);
+    const depKey = `style:file:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+    pushUniqueDependency(
+      stylesheetDependencyKeys,
+      depKey,
+      dependencies,
+      AssetFactory.createFileStylesheet({
+        filepath: resolvedPath,
+        position: "head",
+        attributes: {
+          rel: "stylesheet",
+          ...attributes
+        }
+      })
+    );
+  }
+  for (const script of scriptEntries) {
+    if (isDependencyEntryObject(script) && "lazy" in script && script.lazy) {
+      continue;
+    }
+    const content = getDependencyEntryContent(script);
+    const src = getDependencyEntrySrc(script);
+    const attributes = getDependencyEntryAttributes(script);
+    if (content) {
+      const depKey2 = `script:content:${content}:${JSON.stringify(attributes ?? {})}`;
+      pushUniqueDependency(
+        scriptDependencyKeys,
+        depKey2,
+        dependencies,
+        AssetFactory.createInlineContentScript({
+          position: "head",
+          content,
+          bundle: false,
+          attributes
+        })
+      );
+      continue;
+    }
+    if (!src) {
+      throw new Error(getInvalidScriptEntryMessage());
+    }
+    const resolvedPath = resolveDependencyPath(componentDir, src);
+    const depKey = `script:file:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+    pushUniqueDependency(
+      scriptDependencyKeys,
+      depKey,
+      dependencies,
+      AssetFactory.createFileScript({
+        filepath: resolvedPath,
+        position: "head",
+        attributes: createModuleScriptAttributes(attributes)
+      })
+    );
+  }
+}
+export {
+  collectDeclaredAssetEntries
+};

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

@@ -0,0 +1,35 @@
+import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoPagesAppConfig } from '../../types/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";
+    readonly LAZY_SCRIPT_MISSING_SRC: "Lazy script dependency entry in dependencies.scripts requires a src value";
+};
+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
+     * used when bundling output URLs are unavailable.
+     */
+    resolveLazyScripts(componentDir: string, scripts: string[]): string;
+    /**
+     * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
+     * Lazy dependencies are always resolved into global-injector trigger maps.
+     */
+    processComponentDependencies(components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>, integrationName: string): Promise<ProcessedAsset[]>;
+}

package/src/route-renderer/page-loading/dependency-resolver.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { rapidhash } from "../../utils/hash.js";
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import {
+  buildResolvedLazyTriggers
+} from "./lazy-trigger-planning.js";
+import { collectComponentDependencies } from "./component-dependency-collection.js";
+import { createUnifiedPageDependencies } from "./page-dependency-bundling.js";
+const DEPENDENCY_ERRORS = {
+  INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content",
+  INVALID_SCRIPT_ENTRY: "Invalid script dependency entry: expected src or content",
+  LAZY_SCRIPT_MISSING_SRC: "Lazy script dependency entry in dependencies.scripts requires a src value"
+};
+function resolveLazyScripts(appConfig, componentDir, scripts) {
+  const getSafeFileName = (filepath) => {
+    const EXTENSIONS_TO_JS = ["ts", "tsx"];
+    const safe = filepath.replace(new RegExp(`\\.(${EXTENSIONS_TO_JS.join("|")})$`), ".js");
+    return safe.startsWith("./") ? safe.slice(2) : safe;
+  };
+  const baseDir = componentDir.split(appConfig.srcDir)[1] ?? "";
+  const resolvedPaths = scripts.map((script) => {
+    const relativePath = [AssetFactory.RESOLVED_ASSETS_DIR, baseDir, getSafeFileName(script)].filter(Boolean).join("/").replace(/\/+/g, "/");
+    return `/${relativePath.replace(/^\/+/, "")}`;
+  });
+  return resolvedPaths.join(",");
+}
+const ECOPAGES_JSX_INTEGRATION_NAME = "ecopages-jsx";
+function isEcopagesJsxIntegration(integrationName) {
+  return integrationName === ECOPAGES_JSX_INTEGRATION_NAME;
+}
+function createEcopagesJsxLazyEntryName(integrationName, key) {
+  return `ecopages-${integrationName}-lazy-${rapidhash(key).toString(16)}`;
+}
+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 path.join(componentDir, pathUrl);
+  }
+  /**
+   * Maps lazy script source entries to deterministic fallback public URLs
+   * used when bundling output URLs are unavailable.
+   */
+  resolveLazyScripts(componentDir, scripts) {
+    return resolveLazyScripts(this.appConfig, componentDir, scripts);
+  }
+  /**
+   * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
+   * Lazy dependencies are always resolved into global-injector trigger maps.
+   */
+  async processComponentDependencies(components, integrationName) {
+    if (!this.assetProcessingService?.processDependencies) return [];
+    const { dependencies, lazyScriptsByConfig } = collectComponentDependencies({
+      components,
+      integrationName,
+      resolveLazyScripts: (componentDir, scripts) => this.resolveLazyScripts(componentDir, scripts),
+      createEcopagesJsxLazyEntryName,
+      isEcopagesJsxIntegration,
+      errors: {
+        invalidStylesheetEntry: DEPENDENCY_ERRORS.INVALID_STYLESHEET_ENTRY,
+        invalidScriptEntry: DEPENDENCY_ERRORS.INVALID_SCRIPT_ENTRY,
+        lazyScriptMissingSrc: DEPENDENCY_ERRORS.LAZY_SCRIPT_MISSING_SRC
+      }
+    });
+    const unifiedDependencies = createUnifiedPageDependencies(dependencies, integrationName);
+    const hasLazyDependencies = unifiedDependencies.some(
+      (dep) => dep.kind === "script" && dep.excludeFromHtml === true
+    );
+    const processedDependencies = await this.assetProcessingService.processDependencies(
+      unifiedDependencies,
+      integrationName
+    );
+    const lazyKeyToOutputUrl = /* @__PURE__ */ new Map();
+    for (const dependency of processedDependencies) {
+      if (dependency.kind === "script" && dependency.srcUrl) {
+        const lazyKey = dependency.attributes?.["data-eco-lazy-key"];
+        if (lazyKey) {
+          lazyKeyToOutputUrl.set(lazyKey, dependency.srcUrl);
+        }
+      }
+    }
+    for (const [config, lazyGroupsMap] of lazyScriptsByConfig.entries()) {
+      const rawGroups = [];
+      for (const group of lazyGroupsMap.values()) {
+        const resolvedUrls = group.scripts.map(({ lazyKey, fallbackUrl }) => lazyKeyToOutputUrl.get(lazyKey) ?? fallbackUrl).filter((url) => Boolean(url && url.length > 0));
+        if (resolvedUrls.length === 0) {
+          continue;
+        }
+        rawGroups.push({ lazy: group.lazy, scripts: Array.from(new Set(resolvedUrls)) });
+      }
+      if (hasLazyDependencies) {
+        config._resolvedLazyTriggers = buildResolvedLazyTriggers(config, rawGroups);
+        config._resolvedLazyScripts = void 0;
+      }
+    }
+    return processedDependencies;
+  }
+}
+export {
+  DEPENDENCY_ERRORS,
+  DependencyResolverService
+};

package/src/route-renderer/page-loading/ecopages-virtual-imports.d.ts

@@ -0,0 +1,11 @@
+export type EcopagesVirtualImport = {
+    from: string;
+    imports: string[] | undefined;
+};
+/**
+ * Extracts runtime `ecopages:` virtual-module imports from a component source file.
+ *
+ * Type-only imports are skipped and bare namespace imports are represented by an
+ * `undefined` import list so downstream module generation can preserve that shape.
+ */
+export declare function extractEcopagesVirtualImports(file: string): EcopagesVirtualImport[];