@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

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

@@ -0,0 +1,577 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import {
+  AssetFactory,
+  createPagePackage
+} from "../../services/assets/asset-processing-service/index.js";
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from "../../eco/global-injector-map.js";
+import { LocalsAccessError } from "../../errors/locals-access-error.js";
+import { appLogger } from "../../global/app-logger.js";
+import { inspectUnresolvedMarkerArtifactHtml } from "./render-output.utils.js";
+import { OwnershipValidationService } from "./ownership-validation.service.js";
+import { OwnershipPlanningService } from "./ownership-planning.service.js";
+import { dedupeProcessedAssets } from "./processed-asset-dedupe.js";
+function createPageLocalsProxy(filePath) {
+  const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
+  return new Proxy(
+    {},
+    {
+      get: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      set: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      has: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      ownKeys: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      deleteProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      defineProperty: () => {
+        throw new LocalsAccessError(errorMessage);
+      },
+      getOwnPropertyDescriptor: () => {
+        throw new LocalsAccessError(errorMessage);
+      }
+    }
+  );
+}
+function isGroupedContentScriptAsset(asset) {
+  return asset.kind === "script" && asset.source === "content" && Boolean(asset.groupedBundle?.id);
+}
+function getGroupedBundleAssetKey(groupedBundle) {
+  return `${groupedBundle.id}:${groupedBundle.entryName}`;
+}
+class RouteRenderOrchestrator {
+  appConfig;
+  assetProcessingService;
+  ownershipPlanningService;
+  ownershipValidationService;
+  pageBrowserGraphCache = /* @__PURE__ */ new Map();
+  groupedPageBrowserGraphCache = /* @__PURE__ */ new Map();
+  constructor(appConfig, assetProcessingService, dependencies = {}) {
+    this.appConfig = appConfig;
+    this.assetProcessingService = assetProcessingService;
+    this.ownershipPlanningService = dependencies.ownershipPlanningService ?? new OwnershipPlanningService();
+    this.ownershipValidationService = dependencies.ownershipValidationService ?? new OwnershipValidationService(appConfig);
+  }
+  /**
+   * Builds normalized route render options before the integration render runs.
+   *
+   * This preparation step validates route-root ownership, resolves page data,
+   * collects processed assets, captures optional page-root render metadata, and
+   * produces the page package consumed by downstream HTML transformation.
+   */
+  async prepareRenderOptions(routeOptions, adapter) {
+    const resolvedInputs = await adapter.resolveRouteRenderInputs(routeOptions);
+    const { Page, HtmlTemplate, Layout, props, metadata, integrationSpecificProps } = resolvedInputs;
+    const validationErrors = this.ownershipValidationService.validate({
+      currentIntegrationName: adapter.name,
+      roots: [
+        { component: HtmlTemplate, source: "html-template" },
+        ...Layout ? [{ component: Layout, source: "layout" }] : [],
+        { component: Page, source: "page" }
+      ]
+    });
+    const ownershipPlan = this.ownershipPlanningService.buildPlan({
+      routeFile: routeOptions.file,
+      currentIntegrationName: adapter.name,
+      HtmlTemplate,
+      Layout,
+      Page,
+      validationErrors
+    });
+    const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
+    const { resolvedDependencies } = await adapter.resolveRouteDependencies({
+      components: componentsToResolve
+    });
+    const pageBrowserGraph = await this.resolvePageBrowserGraph({
+      routeFile: routeOptions.file,
+      integrationName: adapter.name,
+      collectContribution: async (routeFile) => await adapter.collectPageBrowserGraphContribution(routeFile)
+    });
+    const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(componentsToResolve, adapter.name);
+    const allDependencies = [...resolvedDependencies, ...usedIntegrationDependencies];
+    const componentRender = await adapter.resolveRoutePageComponentRender({
+      Page,
+      Layout,
+      props,
+      routeOptions
+    });
+    if (componentRender?.assets?.length) {
+      allDependencies.push(...componentRender.assets);
+    }
+    const triggers = this.collectResolvedTriggers(componentsToResolve);
+    if (triggers.length > 0) {
+      const globalAssets = await this.buildGlobalInjectorAssets(triggers, adapter.name);
+      allDependencies.push(...globalAssets);
+    }
+    const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, adapter.name);
+    if (eagerSsrLazyAssets.length > 0) {
+      allDependencies.push(...eagerSsrLazyAssets);
+    }
+    const dedupedDependencies = dedupeProcessedAssets(allDependencies);
+    const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
+    const pageProps = {
+      ...props,
+      params: routeOptions.params || {},
+      query: routeOptions.query || {}
+    };
+    const cacheStrategy = Page.cache;
+    const defaultCacheStrategy = this.appConfig.cache?.defaultStrategy ?? "static";
+    const effectiveCacheStrategy = cacheStrategy ?? defaultCacheStrategy;
+    const localsAvailable = effectiveCacheStrategy === "dynamic" && routeOptions.locals !== void 0;
+    const pageLocals = localsAvailable ? routeOptions.locals : createPageLocalsProxy(routeOptions.file);
+    const locals = localsAvailable ? routeOptions.locals : void 0;
+    const preparedOptions = {
+      ...routeOptions,
+      resolvedDependencies,
+      pagePackage,
+      componentRender,
+      HtmlTemplate,
+      Layout,
+      props,
+      Page,
+      metadata,
+      params: routeOptions.params || {},
+      query: routeOptions.query || {},
+      pageProps,
+      locals,
+      pageLocals,
+      cacheStrategy,
+      ownershipPlan
+    };
+    return {
+      ...integrationSpecificProps,
+      ...preparedOptions
+    };
+  }
+  async resolveDeclaredPageBrowserGraph(input) {
+    return await this.resolvePageBrowserGraph(input);
+  }
+  async resolvePageBrowserGraph(input) {
+    if (this.isHmrEnabled()) {
+      return await this.buildPageBrowserGraph(input);
+    }
+    const cacheKey = `${input.integrationName}:${input.routeFile}`;
+    const cachedGraph = this.pageBrowserGraphCache.get(cacheKey);
+    if (cachedGraph) {
+      return await cachedGraph;
+    }
+    const pendingGraph = this.buildPageBrowserGraph(input).catch((error) => {
+      this.pageBrowserGraphCache.delete(cacheKey);
+      throw error;
+    });
+    this.pageBrowserGraphCache.set(cacheKey, pendingGraph);
+    return await pendingGraph;
+  }
+  isHmrEnabled() {
+    return typeof this.assetProcessingService.getHmrManager === "function" && this.assetProcessingService.getHmrManager()?.isEnabled() === true;
+  }
+  async buildPageBrowserGraph(input) {
+    const contribution = await input.collectContribution(input.routeFile);
+    if (!contribution) {
+      return void 0;
+    }
+    const groupedDependencies = (contribution.dependencies ?? []).filter((dep) => isGroupedContentScriptAsset(dep));
+    const ungroupedDependencies = (contribution.dependencies ?? []).filter(
+      (dep) => !isGroupedContentScriptAsset(dep)
+    );
+    const groupedAssets = groupedDependencies.length ? (await this.resolveGroupedPageBrowserAssets(input, contribution)).get(input.routeFile) ?? [] : [];
+    const processedDependencies = ungroupedDependencies.length ? await this.assetProcessingService.processDependencies(
+      ungroupedDependencies,
+      `${input.integrationName}:${input.routeFile}`
+    ) : [];
+    const resolvedAssets = [...processedDependencies, ...groupedAssets, ...contribution.assets ?? []];
+    return this.partitionPageBrowserGraphAssets(resolvedAssets);
+  }
+  /**
+   * Resolves grouped page-browser assets for all routes owned by one integration.
+   *
+   * @remarks
+   * This keeps one shared browser-build result available across sibling routes so
+   * navigation can reuse the same emitted client graph instead of rebuilding one
+   * page entry at a time. HMR bypasses this cache because the grouped build must
+   * reflect the latest source on every request.
+   */
+  async resolveGroupedPageBrowserAssets(input, currentContribution) {
+    if (this.isHmrEnabled()) {
+      const result = await this.buildGroupedPageBrowserAssets(input, currentContribution);
+      return result.assetsByRoute;
+    }
+    const cacheKey = input.integrationName;
+    const cached = this.groupedPageBrowserGraphCache.get(cacheKey);
+    if (cached) {
+      return await cached;
+    }
+    const pendingGroupedAssets = this.buildGroupedPageBrowserAssets(input, currentContribution).then((result) => {
+      if (result.hasCollectionFailures) {
+        this.groupedPageBrowserGraphCache.delete(cacheKey);
+      }
+      return result.assetsByRoute;
+    }).catch((error) => {
+      this.groupedPageBrowserGraphCache.delete(cacheKey);
+      throw error;
+    });
+    this.groupedPageBrowserGraphCache.set(cacheKey, pendingGroupedAssets);
+    return await pendingGroupedAssets;
+  }
+  /**
+   * Builds the shared grouped page-browser asset map for one integration.
+   *
+   * @remarks
+   * Each route can declare grouped content-script dependencies that should be
+   * emitted together. This method collects those declarations across the owning
+   * integration, runs the grouped processor once, and then maps the emitted
+   * assets back onto the routes that reference them.
+   */
+  async buildGroupedPageBrowserAssets(input, currentContribution) {
+    const routeFiles = await this.listIntegrationRouteFiles(input.integrationName);
+    const currentRouteGroupedDependencies = (currentContribution.dependencies ?? []).filter(
+      (dep) => isGroupedContentScriptAsset(dep)
+    );
+    const groupedDependencies = [...currentRouteGroupedDependencies];
+    const groupedAssetKeysByRoute = /* @__PURE__ */ new Map();
+    let hasCollectionFailures = false;
+    if (currentRouteGroupedDependencies.length > 0) {
+      groupedAssetKeysByRoute.set(
+        input.routeFile,
+        new Set(currentRouteGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle)))
+      );
+    }
+    for (const routeFile of routeFiles) {
+      if (routeFile === input.routeFile) {
+        continue;
+      }
+      let contribution;
+      try {
+        contribution = await input.collectContribution(routeFile);
+      } catch (error) {
+        hasCollectionFailures = true;
+        appLogger.warn(
+          `Skipping grouped page-browser contribution for ${routeFile}: ${error instanceof Error ? error.message : String(error)}`
+        );
+        continue;
+      }
+      if (!contribution?.dependencies?.length) {
+        continue;
+      }
+      const routeGroupedDependencies = contribution.dependencies.filter(
+        (dep) => isGroupedContentScriptAsset(dep)
+      );
+      if (routeGroupedDependencies.length === 0) {
+        continue;
+      }
+      groupedDependencies.push(...routeGroupedDependencies);
+      groupedAssetKeysByRoute.set(
+        routeFile,
+        new Set(routeGroupedDependencies.map((dep) => getGroupedBundleAssetKey(dep.groupedBundle)))
+      );
+    }
+    if (groupedDependencies.length === 0) {
+      return {
+        assetsByRoute: /* @__PURE__ */ new Map(),
+        hasCollectionFailures
+      };
+    }
+    const processedGroupedDependencies = await this.assetProcessingService.processDependencies(
+      groupedDependencies,
+      `${input.integrationName}:grouped-page-browser-graph`
+    );
+    const groupedAssetsByRoute = /* @__PURE__ */ new Map();
+    for (const [routeFile, groupedAssetKeys] of groupedAssetKeysByRoute) {
+      groupedAssetsByRoute.set(
+        routeFile,
+        processedGroupedDependencies.filter((asset) => {
+          if (!asset.groupedBundle) {
+            return false;
+          }
+          return groupedAssetKeys.has(getGroupedBundleAssetKey(asset.groupedBundle));
+        })
+      );
+    }
+    return {
+      assetsByRoute: groupedAssetsByRoute,
+      hasCollectionFailures
+    };
+  }
+  async listIntegrationRouteFiles(integrationName) {
+    const integration = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
+    if (!integration) {
+      return [];
+    }
+    const scannedFiles = await fileSystem.glob(
+      integration.extensions.map((extension) => `**/*${extension}`),
+      { cwd: this.appConfig.absolutePaths.pagesDir }
+    );
+    return scannedFiles.filter((file) => !file.includes(".ecopages-node.")).map((file) => path.join(this.appConfig.absolutePaths.pagesDir, file)).sort((left, right) => left.localeCompare(right));
+  }
+  partitionPageBrowserGraphAssets(assets) {
+    const entryAssets = [];
+    const chunkAssets = [];
+    for (const asset of assets) {
+      if (asset.packageRole === "dynamic-chunk") {
+        chunkAssets.push(asset);
+        continue;
+      }
+      entryAssets.push(asset);
+    }
+    return { entryAssets, chunkAssets };
+  }
+  /**
+   * Captures one route render body as HTML while preserving a replayable body value.
+   */
+  async captureHtmlRender(render) {
+    const renderedBody = await render();
+    const capturedRender = await this.captureRenderedBody(renderedBody);
+    return {
+      body: capturedRender.body,
+      html: capturedRender.html
+    };
+  }
+  /**
+   * Executes the full route-render flow and returns the final body plus cache strategy.
+   */
+  async execute(options, adapter) {
+    const renderOptions = await this.prepareRenderOptions(options, adapter);
+    return this.executePrepared(renderOptions, adapter);
+  }
+  /**
+   * Executes the route-render finalization path for already prepared render options.
+   */
+  async executePrepared(renderOptions, adapter) {
+    const renderExecution = await this.captureHtmlRender(async () => adapter.renderRouteBody(renderOptions));
+    const unresolvedArtifactInspection = inspectUnresolvedMarkerArtifactHtml(renderExecution.html);
+    const htmlFinalization = adapter.getRouteHtmlFinalization(renderOptions);
+    const hasUnresolvedMarkerHtml = unresolvedArtifactInspection.hasUnresolvedMarkerArtifacts;
+    if (hasUnresolvedMarkerHtml) {
+      throw new Error(
+        "[ecopages] Route render returned unresolved eco-marker artifact HTML. Full-route unresolved-marker fallback has been removed; resolve mixed foreign children inside renderComponentWithForeignChildren()."
+      );
+    }
+    const canReuseCapturedBody = !hasUnresolvedMarkerHtml && htmlFinalization.finalizeHtml === void 0;
+    if (canReuseCapturedBody) {
+      const body2 = await adapter.transformRouteResponse(
+        new Response(renderExecution.body, {
+          headers: {
+            "Content-Type": "text/html"
+          }
+        }),
+        htmlFinalization.htmlContributions
+      );
+      return {
+        body: body2,
+        cacheStrategy: renderOptions.cacheStrategy
+      };
+    }
+    const finalization = htmlFinalization.finalizeHtml ? htmlFinalization.finalizeHtml(unresolvedArtifactInspection.normalizedHtml) : unresolvedArtifactInspection.normalizedHtml;
+    const body = await adapter.transformRouteResponse(
+      new Response(finalization, {
+        headers: {
+          "Content-Type": "text/html"
+        }
+      }),
+      htmlFinalization.htmlContributions
+    );
+    return {
+      body,
+      cacheStrategy: renderOptions.cacheStrategy
+    };
+  }
+  async captureRenderedBody(body) {
+    const response = new Response(body);
+    if (typeof body === "string") {
+      return {
+        body,
+        html: await response.text()
+      };
+    }
+    if (!response.body) {
+      return {
+        body,
+        html: await response.text()
+      };
+    }
+    const [capturedBody, replayBody] = response.body.tee();
+    return {
+      body: replayBody,
+      html: await new Response(capturedBody).text()
+    };
+  }
+  collectResolvedTriggers(components, seen = /* @__PURE__ */ new Set()) {
+    const triggers = [];
+    for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
+      const ecoComp = comp;
+      if (seen.has(ecoComp)) {
+        continue;
+      }
+      seen.add(ecoComp);
+      const ownTriggers = ecoComp.config?._resolvedLazyTriggers;
+      if (ownTriggers?.length) {
+        triggers.push(...ownTriggers);
+      }
+      const nested = ecoComp.config?.dependencies?.components;
+      if (nested?.length) {
+        triggers.push(...this.collectResolvedTriggers(nested, seen));
+      }
+    }
+    return triggers;
+  }
+  collectUsedIntegrationDependencies(components, currentIntegrationName) {
+    const integrationNames = this.collectIntegrationNames(components);
+    const dependencies = [];
+    for (const integrationName of integrationNames) {
+      if (integrationName === currentIntegrationName) {
+        continue;
+      }
+      const integrationPlugin = this.appConfig.integrations.find(
+        (integration) => integration.name === integrationName
+      );
+      if (!integrationPlugin || typeof integrationPlugin.getResolvedIntegrationDependencies !== "function") {
+        continue;
+      }
+      dependencies.push(...integrationPlugin.getResolvedIntegrationDependencies());
+    }
+    return dependencies;
+  }
+  collectIntegrationNames(components, seen = /* @__PURE__ */ new Set()) {
+    const integrationNames = /* @__PURE__ */ new Set();
+    for (const comp of components) {
+      if (!comp) {
+        continue;
+      }
+      const ecoComp = comp;
+      if (seen.has(ecoComp)) {
+        continue;
+      }
+      seen.add(ecoComp);
+      const integrationName = ecoComp.config?.integration ?? ecoComp.config?.__eco?.integration;
+      if (integrationName) {
+        integrationNames.add(integrationName);
+      }
+      const nested = ecoComp.config?.dependencies?.components;
+      if (nested?.length) {
+        const nestedNames = this.collectIntegrationNames(nested, seen);
+        for (const nestedName of nestedNames) {
+          integrationNames.add(nestedName);
+        }
+      }
+    }
+    return integrationNames;
+  }
+  async buildGlobalInjectorAssets(triggers, currentIntegrationName) {
+    const appProjectDir = this.appConfig.rootDir ?? this.appConfig.absolutePaths?.projectDir ?? process.cwd();
+    const appPackageRequire = createRequire(path.join(appProjectDir, "package.json"));
+    const corePackageEntryPath = appPackageRequire.resolve("@ecopages/core");
+    const globalInjectorImportPath = createRequire(corePackageEntryPath).resolve(
+      "@ecopages/scripts-injector/global"
+    );
+    const mapScript = AssetFactory.createInlineContentScript({
+      position: "head",
+      name: "ecopages-global-injector-map",
+      content: buildGlobalInjectorMapScript(triggers),
+      attributes: { type: "ecopages/global-injector-map" },
+      packageRole: "keep-separate",
+      bundle: false
+    });
+    const bootstrapInlineScript = AssetFactory.createInlineContentScript({
+      position: "head",
+      name: "ecopages-global-injector-bootstrap",
+      content: buildGlobalInjectorBootstrapContent(globalInjectorImportPath),
+      attributes: { type: "module" },
+      packageRole: "keep-separate",
+      bundle: true
+    });
+    return this.assetProcessingService.processDependencies(
+      [mapScript, bootstrapInlineScript],
+      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 = 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,
+                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"
+            })
+          );
+        }
+      }
+      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 {
+  RouteRenderOrchestrator
+};

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 {};