@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

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

@@ -0,0 +1,132 @@
+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/{dependency-resolver.d.ts → page-loading/dependency-resolver.d.ts}

@@ -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 '../../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";
@@ -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/page-loading/dependency-resolver.js

@@ -0,0 +1,115 @@
+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 { packagePageDependencies } 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 packagedDependencies = packagePageDependencies(dependencies, integrationName);
+    const hasLazyDependencies = packagedDependencies.some(
+      (dep) => dep.kind === "script" && dep.excludeFromHtml === true
+    );
+    const processedDependencies = await this.assetProcessingService.processDependencies(
+      packagedDependencies,
+      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[];

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

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { parseSync } from "oxc-parser";
+function extractEcopagesVirtualImports(file) {
+  let source;
+  try {
+    source = readFileSync(file, "utf-8");
+  } catch {
+    return [];
+  }
+  let result;
+  try {
+    result = parseSync(file, source, { sourceType: "module" });
+  } catch {
+    return [];
+  }
+  const found = /* @__PURE__ */ new Map();
+  for (const node of result.program.body ?? []) {
+    if (node.type !== "ImportDeclaration") continue;
+    if (node.importKind === "type") continue;
+    const specifier = node.source?.value ?? "";
+    if (!specifier.startsWith("ecopages:")) continue;
+    if (found.get(specifier) === null) {
+      continue;
+    }
+    const namedImports = [];
+    for (const spec of node.specifiers ?? []) {
+      if (spec.type === "ImportSpecifier") {
+        let importedName = spec.local?.name;
+        if (spec.imported?.type === "Identifier") {
+          importedName = spec.imported.name;
+        } else if (spec.imported?.type === "Literal") {
+          importedName = spec.imported.value;
+        }
+        namedImports.push(importedName);
+      }
+    }
+    if (namedImports.length === 0) {
+      found.set(specifier, null);
+      continue;
+    }
+    const existing = found.get(specifier);
+    if (!existing) {
+      found.set(specifier, new Set(namedImports));
+      continue;
+    }
+    for (const imported of namedImports) {
+      existing.add(imported);
+    }
+  }
+  return Array.from(found.entries()).map(([from, importsSet]) => ({
+    from,
+    imports: importsSet ? Array.from(importsSet) : void 0
+  }));
+}
+export {
+  extractEcopagesVirtualImports
+};

package/src/route-renderer/page-loading/lazy-entry-collection.d.ts

@@ -0,0 +1,45 @@
+import type { DependencyLazyTrigger, EcoComponentScriptEntry } from '../../types/public-types.js';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.js';
+type LazyScriptRef = {
+    lazyKey: string;
+    fallbackUrl?: string;
+};
+/**
+ * Lazy scripts grouped by one trigger declaration.
+ */
+export type LazyGroup = {
+    lazy: DependencyLazyTrigger;
+    scripts: LazyScriptRef[];
+};
+/**
+ * Callback used to record one normalized lazy-script registration.
+ */
+export type RegisterLazyScript = (input: {
+    lazy: DependencyLazyTrigger;
+    lazyKey: string;
+    fallbackUrl?: string;
+}) => void;
+type CollectLazyEntriesOptions = {
+    scriptEntries: Array<string | EcoComponentScriptEntry>;
+    componentFile: string;
+    componentDir: string;
+    integrationName: string;
+    dependencies: AssetDefinition[];
+    lazyDependencyKeys: Set<string>;
+    registerLazyScript: RegisterLazyScript;
+    resolveDependencyPath: (componentDir: string, pathUrl: string) => string;
+    resolveLazyScripts: (componentDir: string, scripts: string[]) => string;
+    createModuleScriptAttributes: (attributes?: Record<string, string>) => Record<string, string>;
+    createEcopagesJsxLazyEntryName: (integrationName: string, key: string) => string;
+    pushUniqueDependency: (keys: Set<string>, key: string, dependencies: AssetDefinition[], dependency: AssetDefinition) => boolean;
+    getLazyScriptMissingSrcMessage: () => string;
+    isEcopagesJsxIntegration: (integrationName: string) => boolean;
+};
+/**
+ * Collects lazy script dependency entries and emits their hidden bundle inputs.
+ *
+ * This helper also reports the trigger-to-script relationship back to the caller so
+ * later stages can build the lazy-trigger manifest without reparsing dependency config.
+ */
+export declare function collectLazyScriptEntries(options: CollectLazyEntriesOptions): void;
+export {};

package/src/route-renderer/page-loading/lazy-entry-collection.js

@@ -0,0 +1,105 @@
+import { AssetFactory } from "../../services/assets/asset-processing-service/index.js";
+import { rapidhash } from "../../utils/hash.js";
+import { getLazyTriggerKey } from "./lazy-trigger-planning.js";
+function isDependencyEntryObject(entry) {
+  return typeof entry === "object" && entry !== null;
+}
+function getDependencyEntrySrcOrThrow(entry, errorMessage) {
+  if (!entry.src) {
+    throw new Error(errorMessage);
+  }
+  return entry.src;
+}
+function collectLazyScriptEntries(options) {
+  const {
+    scriptEntries,
+    componentFile,
+    componentDir,
+    integrationName,
+    dependencies,
+    lazyDependencyKeys,
+    registerLazyScript,
+    resolveDependencyPath,
+    resolveLazyScripts,
+    createModuleScriptAttributes,
+    createEcopagesJsxLazyEntryName,
+    pushUniqueDependency,
+    getLazyScriptMissingSrcMessage,
+    isEcopagesJsxIntegration
+  } = options;
+  for (const [index, scriptEntry] of scriptEntries.entries()) {
+    if (!isDependencyEntryObject(scriptEntry) || !scriptEntry.lazy) {
+      continue;
+    }
+    const lazy = scriptEntry.lazy;
+    const content = scriptEntry.content;
+    const src = scriptEntry.src;
+    const attributes = scriptEntry.attributes;
+    if (content) {
+      const lazyKey2 = `lazy:${rapidhash(`${componentFile}:entry:${index}:${content}`).toString(16)}`;
+      const depKey2 = `lazy:entry:content:${getLazyTriggerKey(lazy)}:${content}:${JSON.stringify(attributes ?? {})}`;
+      pushUniqueDependency(
+        lazyDependencyKeys,
+        depKey2,
+        dependencies,
+        AssetFactory.createContentScript({
+          position: "head",
+          content,
+          excludeFromHtml: true,
+          attributes: {
+            ...createModuleScriptAttributes(attributes),
+            "data-eco-lazy-key": lazyKey2
+          }
+        })
+      );
+      registerLazyScript({
+        lazy,
+        lazyKey: lazyKey2
+      });
+      continue;
+    }
+    const script = src ?? getDependencyEntrySrcOrThrow(scriptEntry, getLazyScriptMissingSrcMessage());
+    const resolvedPath = resolveDependencyPath(componentDir, script);
+    const fallbackUrl = resolveLazyScripts(componentDir, [script]).split(",")[0] ?? "";
+    const lazyKey = `lazy:${rapidhash(`${resolvedPath}:${getLazyTriggerKey(lazy)}`).toString(16)}`;
+    const lazyEntryName = createEcopagesJsxLazyEntryName(
+      integrationName,
+      `${resolvedPath}:${getLazyTriggerKey(lazy)}`
+    );
+    const depKey = `lazy:entry:file:${getLazyTriggerKey(lazy)}:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+    pushUniqueDependency(
+      lazyDependencyKeys,
+      depKey,
+      dependencies,
+      isEcopagesJsxIntegration(integrationName) ? AssetFactory.createContentScript({
+        name: lazyEntryName,
+        position: "head",
+        content: `import ${JSON.stringify(resolvedPath)};`,
+        excludeFromHtml: true,
+        bundleOptions: {
+          splitting: false
+        },
+        attributes: {
+          ...createModuleScriptAttributes(attributes),
+          "data-eco-lazy-key": lazyKey
+        }
+      }) : AssetFactory.createFileScript({
+        filepath: resolvedPath,
+        position: "head",
+        excludeFromHtml: true,
+        attributes: {
+          ...createModuleScriptAttributes(attributes),
+          "data-eco-lazy-key": lazyKey
+        }
+      })
+    );
+    registerLazyScript({
+      lazy,
+      lazyKey,
+      fallbackUrl
+    });
+  }
+}
+export {
+  collectLazyScriptEntries
+};

package/src/route-renderer/page-loading/lazy-trigger-planning.d.ts

@@ -0,0 +1,19 @@
+import type { DependencyLazyTrigger, EcoComponent, ResolvedLazyTrigger } from '../../types/public-types.js';
+/**
+ * Lazy scripts already normalized onto one trigger and concrete script URL set.
+ */
+export type ResolvedLazyGroup = {
+    lazy: DependencyLazyTrigger;
+    scripts: string[];
+};
+/**
+ * Creates a stable grouping key for a lazy trigger declaration.
+ */
+export declare function getLazyTriggerKey(lazy: DependencyLazyTrigger): string;
+/**
+ * Derives the public lazy-trigger manifest attached to a component config.
+ *
+ * The generated `triggerId` is stable for the same component file and set of
+ * resolved script URLs, independent of declaration order.
+ */
+export declare function buildResolvedLazyTriggers(config: NonNullable<EcoComponent['config']>, groups: ResolvedLazyGroup[]): ResolvedLazyTrigger[];