@ecopages/core 0.2.0-alpha.39 → 0.2.0-alpha.40

package/src/route-renderer/orchestration/integration-renderer.js

@@ -15,6 +15,7 @@ import {
   ForeignSubtreeExecutionService
 } from "./foreign-subtree-execution.service.js";
 import {} from "./queued-foreign-subtree-resolution.service.js";
+import { buildProcessedAssetDedupeKey } from "./processed-asset-dedupe.js";
 function isMarkupNodeLike(value) {
   return typeof value === "object" && value !== null && "nodeType" in value && typeof value.nodeType === "number" && "outerHTML" in value && typeof value.outerHTML === "string";
 }
@@ -179,6 +180,46 @@ class IntegrationRenderer {
     this.htmlTransformer.setPagePackage(createPagePackage(resolvedDependencies));
     return resolvedDependencies;
   }
+  async resolvePageBrowserGraphForFile(filePath) {
+    return await this.routeRenderOrchestrator.resolveDeclaredPageBrowserGraph({
+      routeFile: filePath,
+      integrationName: this.name,
+      collectContribution: async () => {
+        const pageModule = await this.importPageFile(filePath);
+        return await this.collectPageBrowserGraphContribution({ file: filePath, pageModule });
+      }
+    });
+  }
+  mergePageBrowserGraphIntoPagePackage(pageBrowserGraph) {
+    if (!pageBrowserGraph) {
+      return void 0;
+    }
+    const currentPagePackage = this.htmlTransformer.getPagePackage();
+    const mergedPageBrowserGraph = currentPagePackage?.pageBrowserGraph ? {
+      entryAssets: this.htmlTransformer.dedupeProcessedAssets([
+        ...currentPagePackage.pageBrowserGraph.entryAssets,
+        ...pageBrowserGraph.entryAssets
+      ]),
+      chunkAssets: this.htmlTransformer.dedupeProcessedAssets([
+        ...currentPagePackage.pageBrowserGraph.chunkAssets,
+        ...pageBrowserGraph.chunkAssets
+      ])
+    } : pageBrowserGraph;
+    const pageBrowserGraphAssetKeys = new Set(
+      [...mergedPageBrowserGraph.entryAssets, ...mergedPageBrowserGraph.chunkAssets].map(
+        (asset) => buildProcessedAssetDedupeKey(asset)
+      )
+    );
+    const baseAssets = currentPagePackage ? currentPagePackage.assets.filter(
+      (asset) => !pageBrowserGraphAssetKeys.has(buildProcessedAssetDedupeKey(asset))
+    ) : this.htmlTransformer.getProcessedDependencies();
+    this.htmlTransformer.setPagePackage(
+      createPagePackage(this.htmlTransformer.dedupeProcessedAssets(baseAssets), {
+        pageBrowserGraph: mergedPageBrowserGraph
+      })
+    );
+    return mergedPageBrowserGraph;
+  }
   /**
    * Merges component-scoped assets into the active HTML transformer state.
    *
@@ -579,11 +620,15 @@ class IntegrationRenderer {
     return {
       name: this.name,
       resolveRouteRenderInputs: (routeOptions) => this.resolveRouteRenderInputs(routeOptions),
-      resolveRouteAssets: (input) => this.resolveRouteAssets(input),
+      resolveRouteDependencies: (input) => this.resolveRouteDependencies(input),
+      collectPageBrowserGraphContribution: async (routeFile) => {
+        const pageModule = await this.importPageFile(routeFile);
+        return await this.collectPageBrowserGraphContribution({ file: routeFile, pageModule });
+      },
       resolveRoutePageComponentRender: (input) => this.resolveRoutePageComponentRender(input),
       renderRouteBody: (renderOptions) => this.renderRouteBody(renderOptions),
       getRouteHtmlFinalization: (renderOptions) => this.getRouteHtmlFinalization(renderOptions),
-      transformRouteResponse: (response) => this.transformRouteResponse(response)
+      transformRouteResponse: (response, htmlContributions) => this.transformRouteResponse(response, htmlContributions)
     };
   }
   async resolveRouteRenderInputs(routeOptions) {
@@ -607,10 +652,9 @@ class IntegrationRenderer {
       integrationSpecificProps
     };
   }
-  async resolveRouteAssets(input) {
+  async resolveRouteDependencies(input) {
     return {
-      resolvedDependencies: await this.resolveDependencies(input.components),
-      pageBrowserGraph: await this.buildPageBrowserGraph(input.routeOptions.file)
+      resolvedDependencies: await this.resolveDependencies(input.components)
     };
   }
   async resolveRoutePageComponentRender(input) {
@@ -635,11 +679,13 @@ class IntegrationRenderer {
   getRouteHtmlFinalization(renderOptions) {
     const componentRootAttributes = renderOptions.componentRender?.canAttachAttributes && renderOptions.componentRender.rootAttributes && Object.keys(renderOptions.componentRender.rootAttributes).length > 0 ? renderOptions.componentRender.rootAttributes : void 0;
     const documentAttributes = this.getDocumentAttributes(renderOptions);
+    const htmlContributions = this.getHtmlDocumentContributions({ renderOptions, partial: false });
     const hasStructuralFinalization = componentRootAttributes && Object.keys(componentRootAttributes).length > 0 || documentAttributes && Object.keys(documentAttributes).length > 0;
-    if (!hasStructuralFinalization) {
+    if (!hasStructuralFinalization && (!htmlContributions || htmlContributions.length === 0)) {
       return {};
     }
     return {
+      htmlContributions,
       finalizeHtml: (html) => {
         let renderedHtml = html;
         if (componentRootAttributes) {
@@ -655,8 +701,8 @@ class IntegrationRenderer {
       }
     };
   }
-  async transformRouteResponse(response) {
-    const transformedResponse = await this.htmlTransformer.transform(response);
+  async transformRouteResponse(response, htmlContributions) {
+    const transformedResponse = await this.htmlTransformer.transform(response, htmlContributions);
     return transformedResponse.body ?? await transformedResponse.text();
   }
   /**
@@ -726,10 +772,14 @@ class IntegrationRenderer {
     if (!shouldTransform) {
       return html;
     }
+    const htmlContributions = options.htmlContributions ?? this.getHtmlDocumentContributions({
+      partial: options.partial
+    });
     const transformedResponse = await this.htmlTransformer.transform(
       new Response(html, {
         headers: { "Content-Type": "text/html" }
-      })
+      }),
+      htmlContributions
     );
     return await transformedResponse.text();
   }
@@ -742,6 +792,18 @@ class IntegrationRenderer {
   getDocumentAttributes(_renderOptions) {
     return void 0;
   }
+  /**
+   * Returns declarative HTML fragments that core should inject into the final document.
+   *
+   * @remarks
+   * Integrations may contribute document markup here, but core retains ownership
+   * of the final HTML rewrite pipeline and placement semantics. This is the
+   * supported document-markup extension point for integrations instead of custom
+   * response finalization logic.
+   */
+  getHtmlDocumentContributions(_options) {
+    return void 0;
+  }
   /**
    * Returns a renderer instance for a given integration name.
    *
@@ -883,13 +945,17 @@ class IntegrationRenderer {
     return rootTag?.[1];
   }
   /**
-   * Builds the Page Browser Graph owned by this integration for one Page.
-   * This method can be optionally overridden by the specific integration renderer.
+   * Collects declarative Page Browser Graph contributions for one Page.
+   *
+   * @remarks
+   * Integrations may describe page-scoped browser requirements here, while core
+   * retains ownership of dependency processing and final graph assembly. This is
+   * the supported page-browser extension point for integrations.
    *
-   * @param file - The file path to build assets for.
-   * @returns The structured Page Browser Graph or undefined.
+   * @param context - The route file path and already imported page module.
+   * @returns Declarative dependencies or pre-resolved assets for the Page.
    */
-  async buildPageBrowserGraph(_file) {
+  async collectPageBrowserGraphContribution(_context) {
     return void 0;
   }
   /**

package/src/route-renderer/orchestration/processed-asset-dedupe.d.ts

@@ -1,2 +1,3 @@
 import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+export declare function buildProcessedAssetDedupeKey(asset: ProcessedAsset): string;
 export declare function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];

package/src/route-renderer/orchestration/processed-asset-dedupe.js

@@ -1,17 +1,20 @@
+function buildProcessedAssetDedupeKey(asset) {
+  return [
+    asset.kind,
+    asset.position ?? "",
+    asset.srcUrl ?? "",
+    asset.filepath ?? "",
+    asset.content ?? "",
+    asset.inline ? "inline" : "external",
+    asset.excludeFromHtml ? "excluded" : "included",
+    asset.packageRole ?? "",
+    JSON.stringify(asset.attributes ?? {})
+  ].join("|");
+}
 function dedupeProcessedAssets(assets) {
   const unique = /* @__PURE__ */ new Map();
   for (const asset of assets) {
-    const key = [
-      asset.kind,
-      asset.position ?? "",
-      asset.srcUrl ?? "",
-      asset.filepath ?? "",
-      asset.content ?? "",
-      asset.inline ? "inline" : "external",
-      asset.excludeFromHtml ? "excluded" : "included",
-      asset.packageRole ?? "",
-      JSON.stringify(asset.attributes ?? {})
-    ].join("|");
+    const key = buildProcessedAssetDedupeKey(asset);
     if (!unique.has(key)) {
       unique.set(key, asset);
     }
@@ -19,5 +22,6 @@ function dedupeProcessedAssets(assets) {
   return [...unique.values()];
 }
 export {
+  buildProcessedAssetDedupeKey,
   dedupeProcessedAssets
 };

package/src/route-renderer/orchestration/route-render-orchestrator.d.ts

@@ -1,6 +1,7 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderResult, EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 import { OwnershipValidationService } from './ownership-validation.service.js';
 import { OwnershipPlanningService } from './ownership-planning.service.js';
 export type RouteRenderOrchestratorResolvedInputs = {
@@ -11,9 +12,8 @@ export type RouteRenderOrchestratorResolvedInputs = {
     metadata: PageMetadataProps;
     integrationSpecificProps: Record<string, unknown>;
 };
-export type RouteRenderOrchestratorResolvedAssets = {
+export type RouteRenderOrchestratorResolvedDependencies = {
     resolvedDependencies: ProcessedAsset[];
-    pageBrowserGraph?: PageBrowserGraphResult;
 };
 /**
  * Structural HTML work applied after the route body has been fully resolved.
@@ -23,6 +23,7 @@ export type RouteRenderOrchestratorResolvedAssets = {
  */
 export type RouteHtmlFinalization = {
     finalizeHtml?(html: string): string;
+    htmlContributions?: HtmlDocumentContribution[];
 };
 export interface RouteRenderOrchestratorAdapter<C> {
     /**
@@ -34,12 +35,15 @@ export interface RouteRenderOrchestratorAdapter<C> {
      */
     resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
     /**
-     * Resolves route-owned assets needed before Integration rendering starts.
+     * Resolves route-owned dependencies needed before Integration rendering starts.
      */
-    resolveRouteAssets(input: {
-        routeOptions: RouteRendererOptions;
+    resolveRouteDependencies(input: {
         components: (EcoComponent | Partial<EcoComponent>)[];
-    }): Promise<RouteRenderOrchestratorResolvedAssets>;
+    }): Promise<RouteRenderOrchestratorResolvedDependencies>;
+    /**
+     * Collects declarative Page Browser Graph requirements for one route.
+     */
+    collectPageBrowserGraphContribution(routeFile: string): Promise<PageBrowserGraphContribution | undefined>;
     /**
      * Resolves the optional page-root render through the foreign-child-aware component contract.
      */
@@ -60,7 +64,7 @@ export interface RouteRenderOrchestratorAdapter<C> {
     /**
      * Runs SSR-policy response transformation and returns the body value exposed to callers.
      */
-    transformRouteResponse(response: Response): Promise<RouteRendererBody>;
+    transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
 }
 /**
  * Captured route-render output in both replayable body and string HTML forms.
@@ -89,6 +93,7 @@ export declare class RouteRenderOrchestrator {
     private readonly assetProcessingService;
     private readonly ownershipPlanningService;
     private readonly ownershipValidationService;
+    private readonly pageBrowserGraphCache;
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService, dependencies?: RouteRenderOrchestratorDependencies);
     /**
      * Builds normalized route render options before the integration render runs.
@@ -98,6 +103,15 @@ export declare class RouteRenderOrchestrator {
      * produces the page package consumed by downstream HTML transformation.
      */
     prepareRenderOptions<C = unknown>(routeOptions: RouteRendererOptions, adapter: RouteRenderOrchestratorAdapter<C>): Promise<IntegrationRendererRenderOptions<C>>;
+    resolveDeclaredPageBrowserGraph(input: {
+        routeFile: string;
+        integrationName: string;
+        collectContribution: () => Promise<PageBrowserGraphContribution | undefined>;
+    }): Promise<PageBrowserGraphResult | undefined>;
+    private resolvePageBrowserGraph;
+    private isHmrEnabled;
+    private buildPageBrowserGraph;
+    private partitionPageBrowserGraphAssets;
     /**
      * Captures one route render body as HTML while preserving a replayable body value.
      */

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

@@ -44,6 +44,7 @@ class RouteRenderOrchestrator {
   assetProcessingService;
   ownershipPlanningService;
   ownershipValidationService;
+  pageBrowserGraphCache = /* @__PURE__ */ new Map();
   constructor(appConfig, assetProcessingService, dependencies = {}) {
     this.appConfig = appConfig;
     this.assetProcessingService = assetProcessingService;
@@ -77,16 +78,16 @@ class RouteRenderOrchestrator {
       validationErrors
     });
     const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
-    const { resolvedDependencies, pageBrowserGraph } = await adapter.resolveRouteAssets({
-      routeOptions,
+    const { resolvedDependencies } = await adapter.resolveRouteDependencies({
       components: componentsToResolve
     });
+    const pageBrowserGraph = await this.resolvePageBrowserGraph({
+      routeFile: routeOptions.file,
+      integrationName: adapter.name,
+      collectContribution: async () => await adapter.collectPageBrowserGraphContribution(routeOptions.file)
+    });
     const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(componentsToResolve, adapter.name);
-    const allDependencies = [
-      ...resolvedDependencies,
-      ...usedIntegrationDependencies,
-      ...pageBrowserGraph?.assets ?? []
-    ];
+    const allDependencies = [...resolvedDependencies, ...usedIntegrationDependencies];
     const componentRender = await adapter.resolveRoutePageComponentRender({
       Page,
       Layout,
@@ -106,7 +107,7 @@ class RouteRenderOrchestrator {
       allDependencies.push(...eagerSsrLazyAssets);
     }
     const dedupedDependencies = dedupeProcessedAssets(allDependencies);
-    const pagePackage = createPagePackage(dedupedDependencies);
+    const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
     const pageProps = {
       ...props,
       params: routeOptions.params || {},
@@ -141,6 +142,52 @@ class RouteRenderOrchestrator {
       ...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();
+    if (!contribution) {
+      return void 0;
+    }
+    const processedDependencies = contribution.dependencies?.length ? await this.assetProcessingService.processDependencies(
+      contribution.dependencies,
+      `${input.integrationName}:${input.routeFile}`
+    ) : [];
+    const resolvedAssets = [...processedDependencies, ...contribution.assets ?? []];
+    return this.partitionPageBrowserGraphAssets(resolvedAssets);
+  }
+  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.
    */
@@ -179,7 +226,8 @@ class RouteRenderOrchestrator {
           headers: {
             "Content-Type": "text/html"
           }
-        })
+        }),
+        htmlFinalization.htmlContributions
       );
       return {
         body: body2,
@@ -192,7 +240,8 @@ class RouteRenderOrchestrator {
         headers: {
           "Content-Type": "text/html"
         }
-      })
+      }),
+      htmlFinalization.htmlContributions
     );
     return {
       body,

package/src/services/assets/asset-processing-service/page-package.d.ts

@@ -1,3 +1,6 @@
 import type { PagePackageResult } from '../../../types/public-types.js';
 import type { ProcessedAsset } from './assets.types.js';
-export declare function createPagePackage(assets: ProcessedAsset[]): PagePackageResult;
+import type { PageBrowserGraphResult } from '../../../types/public-types.js';
+export declare function createPagePackage(assets: ProcessedAsset[], options?: {
+    pageBrowserGraph?: PageBrowserGraphResult;
+}): PagePackageResult;

package/src/services/assets/asset-processing-service/page-package.js

@@ -9,14 +9,19 @@ function getSuppressedSourceFilepaths(assets) {
   }
   return suppressed;
 }
-function createPagePackage(assets) {
+function createPagePackage(assets, options = {}) {
+  const allAssets = [
+    ...assets,
+    ...options.pageBrowserGraph?.entryAssets ?? [],
+    ...options.pageBrowserGraph?.chunkAssets ?? []
+  ];
   const inlineAssets = [];
   const separateAssets = [];
   const dynamicChunks = [];
   let pageScript;
   let pageStylesheet;
-  const suppressedSourceFilepaths = getSuppressedSourceFilepaths(assets);
-  for (const asset of assets) {
+  const suppressedSourceFilepaths = getSuppressedSourceFilepaths(allAssets);
+  for (const asset of allAssets) {
     if (asset.inline) {
       inlineAssets.push(asset);
       continue;
@@ -48,8 +53,9 @@ function createPagePackage(assets) {
     separateAssets.push(asset);
   }
   return {
-    assets,
-    htmlAssets: assets.filter((asset) => shouldIncludeInHtml(asset, suppressedSourceFilepaths)),
+    assets: allAssets,
+    pageBrowserGraph: options.pageBrowserGraph,
+    htmlAssets: allAssets.filter((asset) => shouldIncludeInHtml(asset, suppressedSourceFilepaths)),
     pageScript,
     pageStylesheet,
     inlineAssets,

package/src/services/assets/asset-processing-service/processors/script/node-module-script.processor.js

@@ -78,7 +78,9 @@ class NodeModuleScriptProcessor extends BaseScriptProcessor {
    */
   resolveModulePathFallback(importPath, rootDir, maxDepth = 5) {
     try {
-      return fileURLToPath(import.meta.resolve(importPath, pathToFileURL(path.join(rootDir, "package.json")).href));
+      return fileURLToPath(
+        import.meta.resolve(importPath, pathToFileURL(path.join(rootDir, "package.json")).href)
+      );
     } catch {
     }
     let currentDir = rootDir;

package/src/services/html/html-rewriter-provider.service.d.ts

@@ -1,4 +1,7 @@
 export type HtmlRewriterElement = {
+    prepend(content: string, options?: {
+        html?: boolean;
+    }): void;
     append(content: string, options?: {
         html?: boolean;
     }): void;

package/src/services/html/html-transformer.service.d.ts

@@ -1,6 +1,11 @@
 import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types.js';
 import type { PagePackageResult } from '../../types/public-types.js';
 import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service.js';
+export type HtmlDocumentContributionPlacement = 'head-prepend' | 'head-append' | 'body-prepend' | 'body-append';
+export type HtmlDocumentContribution = {
+    placement: HtmlDocumentContributionPlacement;
+    html: string;
+};
 export interface HtmlTransformerServiceOptions {
     htmlRewriterMode?: HtmlRewriterMode;
     htmlRewriterProvider?: HtmlRewriterProvider;
@@ -24,11 +29,14 @@ export declare class HtmlTransformerService {
     private generateStylesheetTag;
     private appendDependencies;
     private buildDependencyTags;
+    private applyContributions;
     /**
      * Injects generated markup immediately before the closing HTML tag when it is
      * present, or appends/prepends a fallback insertion otherwise.
      */
     private injectBeforeClosingTag;
+    private injectAfterOpeningTag;
+    private groupContributionsByPlacement;
     /**
      * Replaces the current processed dependency set used during HTML finalization.
      */
@@ -75,11 +83,12 @@ export declare class HtmlTransformerService {
      * string-based fallback remains in place for runtimes that cannot provide one
      * of those rewriter implementations.
      */
-    transform(res: Response): Promise<Response>;
+    transform(res: Response, contributions?: HtmlDocumentContribution[]): Promise<Response>;
     /**
      * Splits processed assets into head and body injection groups.
      */
     private groupDependenciesByPosition;
+    private resolvePagePackageHtmlDependencies;
     /**
      * Builds a serialized HTML attribute string from an attribute object.
      */

package/src/services/html/html-transformer.service.js

@@ -1,7 +1,10 @@
 import {
   DefaultHtmlRewriterProvider
 } from "./html-rewriter-provider.service.js";
-import { dedupeProcessedAssets } from "../../route-renderer/orchestration/processed-asset-dedupe.js";
+import {
+  buildProcessedAssetDedupeKey,
+  dedupeProcessedAssets
+} from "../../route-renderer/orchestration/processed-asset-dedupe.js";
 class HtmlTransformerService {
   processedDependencies = [];
   pagePackage;
@@ -44,6 +47,11 @@ class HtmlTransformerService {
       (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
     ).join("");
   }
+  applyContributions(element, contributions, placement) {
+    for (const contribution of contributions) {
+      element[placement](contribution.html, { html: true });
+    }
+  }
   /**
    * Injects generated markup immediately before the closing HTML tag when it is
    * present, or appends/prepends a fallback insertion otherwise.
@@ -63,6 +71,26 @@ class HtmlTransformerService {
     }
     return `${html}${content}`;
   }
+  injectAfterOpeningTag(html, tag, content) {
+    if (!content) {
+      return html;
+    }
+    const openingTag = new RegExp(`<${tag}\\b[^>]*>`, "i");
+    const match = html.match(openingTag);
+    if (!match || match.index === void 0) {
+      return tag === "head" ? `${content}${html}` : html.replace(/<body\b[^>]*>/i, (value) => `${value}${content}`);
+    }
+    const insertAt = match.index + match[0].length;
+    return `${html.slice(0, insertAt)}${content}${html.slice(insertAt)}`;
+  }
+  groupContributionsByPlacement(contributions) {
+    return {
+      headPrepend: contributions.filter((item) => item.placement === "head-prepend"),
+      headAppend: contributions.filter((item) => item.placement === "head-append"),
+      bodyPrepend: contributions.filter((item) => item.placement === "body-prepend"),
+      bodyAppend: contributions.filter((item) => item.placement === "body-append")
+    };
+  }
   /**
    * Replaces the current processed dependency set used during HTML finalization.
    */
@@ -75,7 +103,7 @@ class HtmlTransformerService {
    */
   setPagePackage(pagePackage) {
     this.pagePackage = pagePackage;
-    this.processedDependencies = pagePackage.htmlAssets;
+    this.processedDependencies = this.resolvePagePackageHtmlDependencies(pagePackage);
   }
   /**
    * Returns the processed dependencies queued for the next transform pass.
@@ -160,24 +188,47 @@ class HtmlTransformerService {
    * string-based fallback remains in place for runtimes that cannot provide one
    * of those rewriter implementations.
    */
-  async transform(res) {
+  async transform(res, contributions = []) {
     const { head, body } = this.groupDependenciesByPosition();
+    const { headPrepend, headAppend, bodyPrepend, bodyAppend } = this.groupContributionsByPlacement(contributions);
     const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
     if (htmlRewriter) {
       htmlRewriter.on("head", {
-        element: (element) => this.appendDependencies(element, head)
+        element: (element) => {
+          this.applyContributions(element, headPrepend, "prepend");
+          this.appendDependencies(element, head);
+          this.applyContributions(element, headAppend, "append");
+        }
       }).on("body", {
-        element: (element) => this.appendDependencies(element, body)
+        element: (element) => {
+          this.applyContributions(element, bodyPrepend, "prepend");
+          this.appendDependencies(element, body);
+          this.applyContributions(element, bodyAppend, "append");
+        }
       });
       return htmlRewriter.transform(res);
     }
     const html = await res.text();
     const headers = new Headers(res.headers);
-    const withHeadDependencies = this.injectBeforeClosingTag(html, "head", this.buildDependencyTags(head));
-    const transformedHtml = this.injectBeforeClosingTag(
+    const withHeadPrependedContent = this.injectAfterOpeningTag(
+      html,
+      "head",
+      headPrepend.map((item) => item.html).join("")
+    );
+    const withHeadDependencies = this.injectBeforeClosingTag(
+      withHeadPrependedContent,
+      "head",
+      `${this.buildDependencyTags(head)}${headAppend.map((item) => item.html).join("")}`
+    );
+    const withBodyPrependedContent = this.injectAfterOpeningTag(
       withHeadDependencies,
       "body",
-      this.buildDependencyTags(body)
+      bodyPrepend.map((item) => item.html).join("")
+    );
+    const transformedHtml = this.injectBeforeClosingTag(
+      withBodyPrependedContent,
+      "body",
+      `${this.buildDependencyTags(body)}${bodyAppend.map((item) => item.html).join("")}`
     );
     return new Response(transformedHtml, {
       headers,
@@ -189,7 +240,7 @@ class HtmlTransformerService {
    * Splits processed assets into head and body injection groups.
    */
   groupDependenciesByPosition() {
-    const dependencies = this.pagePackage?.htmlAssets ?? this.processedDependencies;
+    const dependencies = this.pagePackage ? this.resolvePagePackageHtmlDependencies(this.pagePackage) : this.processedDependencies;
     return dependencies.reduce(
       (acc, dep) => {
         if (dep.kind === "script") {
@@ -204,6 +255,26 @@ class HtmlTransformerService {
       { head: [], body: [] }
     );
   }
+  resolvePagePackageHtmlDependencies(pagePackage) {
+    if (!pagePackage.pageBrowserGraph) {
+      return pagePackage.htmlAssets;
+    }
+    const chunkKeys = new Set(
+      pagePackage.pageBrowserGraph.chunkAssets.map((asset) => buildProcessedAssetDedupeKey(asset))
+    );
+    const graphKeys = new Set(
+      [...pagePackage.pageBrowserGraph.entryAssets, ...pagePackage.pageBrowserGraph.chunkAssets].map(
+        (asset) => buildProcessedAssetDedupeKey(asset)
+      )
+    );
+    const nonGraphHtmlAssets = pagePackage.htmlAssets.filter(
+      (asset) => !graphKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    const entryHtmlAssets = pagePackage.pageBrowserGraph.entryAssets.filter(
+      (asset) => !chunkKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    return dedupeProcessedAssets([...nonGraphHtmlAssets, ...entryHtmlAssets]);
+  }
   /**
    * Builds a serialized HTML attribute string from an attribute object.
    */