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

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -0,0 +1,46 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+function normalizeOriginHostname(hostname) {
+  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
+    return `[${hostname}]`;
+  }
+  return hostname;
+}
+function resolveServeRuntimeOrigin(serveOptions) {
+  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+  return `http://${hostname}:${port}`;
+}
+function resolveRuntimeBinding(options) {
+  const env = options.env ?? process.env;
+  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+  return {
+    preferredPort,
+    preferredHostname,
+    runtimeOrigin: resolveServeRuntimeOrigin({
+      hostname: preferredHostname,
+      port: preferredPort
+    }),
+    serveOptions: {
+      port: preferredPort,
+      hostname: preferredHostname,
+      ...options.serverOptions ?? {}
+    },
+    watch: options.cliArgs.dev
+  };
+}
+function resolveStaticRuntimeMode(options) {
+  const requiresFetchRuntime = options.appConfig.integrations.some(
+    (integration) => integration.staticBuildStep === "fetch"
+  );
+  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
+  return {
+    requiresFetchRuntime,
+    canBuildWithoutRuntimeServer
+  };
+}
+export {
+  resolveRuntimeBinding,
+  resolveServeRuntimeOrigin,
+  resolveStaticRuntimeMode
+};

package/src/adapters/shared/runtime-host.d.ts

@@ -0,0 +1,12 @@
+export interface RuntimeHost<TServer, TServeOptions> {
+    start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
+    stop(server: TServer, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
+}
+export interface RuntimeHostStartOptions<TServeOptions> {
+    serveOptions: TServeOptions;
+    handleRequest(request: Request): Promise<Response>;
+    onError(error: Error): Promise<void> | void;
+}

package/src/adapters/shared/shared-hmr-manager.d.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import type { DefaultHmrContext, EcoPagesAppConfig, IHmrManager, IClientBridge } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import { type HmrStrategy } from '../../hmr/hmr-strategy.js';
+import type { ClientBridgeEvent } from '../../types/public-types.js';
+import { HmrEntrypointRegistrar } from './hmr-entrypoint-registrar.js';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
+import { type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.js';
+type HandleFileChangeOptions = {
+    broadcast?: boolean;
+};
+type SharedHmrManagerParams = {
+    appConfig: EcoPagesAppConfig;
+    bridge: IClientBridge;
+    registrationTimeoutMs?: number;
+};
+export declare abstract class SharedHmrManager implements IHmrManager {
+    readonly appConfig: EcoPagesAppConfig;
+    protected readonly bridge: IClientBridge;
+    protected watchers: Map<string, fs.FSWatcher>;
+    protected watchedFiles: Map<string, string>;
+    protected entrypointRegistrations: Map<string, Promise<string>>;
+    protected distDir: string;
+    protected plugins: EcoBuildPlugin[];
+    protected enabled: boolean;
+    protected strategies: HmrStrategy[];
+    protected readonly entrypointRegistrar: HmrEntrypointRegistrar;
+    protected readonly browserBundleService: BrowserBundleService;
+    protected readonly entrypointDependencyGraph: EntrypointDependencyGraph;
+    protected readonly serverModuleTranspiler: ServerModuleTranspiler;
+    constructor({ appConfig, bridge, registrationTimeoutMs }: SharedHmrManagerParams);
+    protected abstract createEntrypointDependencyGraph(existingEntrypointDependencyGraph: EntrypointDependencyGraph): EntrypointDependencyGraph;
+    protected shouldSkipMissingFileChange(_filePath: string): boolean;
+    protected onRuntimeBundleFailure(error: unknown): void;
+    protected ensureDistDir(): void;
+    protected shouldJsStrategyProcessEntrypoint(entrypointPath: string): boolean;
+    protected initializeStrategies(): void;
+    registerStrategy(strategy: HmrStrategy): void;
+    setPlugins(plugins: EcoBuildPlugin[]): void;
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    buildRuntime(): Promise<void>;
+    getRuntimePath(): string;
+    broadcast(event: ClientBridgeEvent): void;
+    handleFileChange(filePath: string, options?: HandleFileChangeOptions): Promise<void>;
+    getOutputUrl(entrypointPath: string): string | undefined;
+    getWatchedFiles(): Map<string, string>;
+    getDistDir(): string;
+    getPlugins(): EcoBuildPlugin[];
+    getDefaultContext(): DefaultHmrContext;
+    protected clearFailedEntrypointRegistration(entrypointPath: string): void;
+    registerEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    protected emitStrictEntrypoint(entrypointPath: string): Promise<void>;
+    protected emitScriptEntrypoint(entrypointPath: string, outputPath: string): Promise<void>;
+    stop(): void;
+}
+export {};

package/src/adapters/shared/shared-hmr-manager.js

@@ -0,0 +1,239 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { getAppBuildExecutor } from "../../build/build-adapter.js";
+import { fileSystem } from "@ecopages/file-system";
+import { HmrStrategyType } from "../../hmr/hmr-strategy.js";
+import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy.js";
+import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy.js";
+import { appLogger } from "../../global/app-logger.js";
+import { HmrEntrypointRegistrar } from "./hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
+import {
+  getAppEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+class SharedHmrManager {
+  appConfig;
+  bridge;
+  watchers = /* @__PURE__ */ new Map();
+  watchedFiles = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
+  distDir;
+  plugins = [];
+  enabled = true;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  serverModuleTranspiler;
+  constructor({ appConfig, bridge, registrationTimeoutMs = 4e3 }) {
+    this.appConfig = appConfig;
+    this.bridge = bridge;
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    this.entrypointDependencyGraph = this.createEntrypointDependencyGraph(
+      getAppEntrypointDependencyGraph(appConfig)
+    );
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.ensureDistDir();
+    this.initializeStrategies();
+  }
+  shouldSkipMissingFileChange(_filePath) {
+    return false;
+  }
+  onRuntimeBundleFailure(error) {
+    appLogger.error("[HMR] Failed to build runtime script:", error);
+  }
+  ensureDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  shouldJsStrategyProcessEntrypoint(entrypointPath) {
+    return !this.strategies.some((strategy) => {
+      if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+        return false;
+      }
+      try {
+        return strategy.matches(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  initializeStrategies() {
+    const jsContext = {
+      getWatchedFiles: () => this.watchedFiles,
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
+    };
+    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  }
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setPlugins(plugins) {
+    this.plugins = [...plugins];
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  async buildRuntime() {
+    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
+    try {
+      const result = await this.browserBundleService.bundle({
+        profile: "hmr-runtime",
+        entrypoints: [runtimeSource],
+        outdir: this.distDir,
+        naming: "_hmr_runtime.js",
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!result.success) {
+        this.onRuntimeBundleFailure(result.logs);
+      }
+    } catch (error) {
+      this.onRuntimeBundleFailure(error);
+    }
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  broadcast(event) {
+    appLogger.debug(
+      `[HMR] Broadcasting ${event.type} event, path=${event.path || "all"}, subscribers=${this.bridge.subscriberCount}`
+    );
+    this.bridge.broadcast(event);
+  }
+  async handleFileChange(filePath, options = {}) {
+    if (this.shouldSkipMissingFileChange(filePath) && !fileSystem.exists(filePath)) {
+      appLogger.debug(`[${this.constructor.name}] Skipping missing file change: ${filePath}`);
+      this.clearFailedEntrypointRegistration(filePath);
+      return;
+    }
+    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+    const strategy = sorted.find((candidate) => {
+      try {
+        return candidate.matches(filePath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[${this.constructor.name}] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast" && action.events) {
+      for (const event of action.events) {
+        this.broadcast(event);
+      }
+    }
+  }
+  getOutputUrl(entrypointPath) {
+    return this.watchedFiles.get(entrypointPath);
+  }
+  getWatchedFiles() {
+    return this.watchedFiles;
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getPlugins() {
+    return this.plugins;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.watchedFiles,
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+    this.entrypointDependencyGraph.clearEntrypointDependencies(entrypointPath);
+  }
+  async registerEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint) => await this.emitStrictEntrypoint(normalizedEntrypoint),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  async emitStrictEntrypoint(entrypointPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    const buildResult = await this.browserBundleService.bundle({
+      profile: "hmr-entrypoint",
+      entrypoints: [entrypointPath],
+      outdir: this.distDir,
+      naming,
+      minify: false,
+      plugins: this.plugins
+    });
+    if (!buildResult.success) {
+      appLogger.error(`[HMR] Generic script entrypoint build failed for ${entrypointPath}:`, buildResult.logs);
+      return;
+    }
+    const entrypointDependencies = buildResult.dependencyGraph?.entrypoints?.[entrypointPath];
+    if (entrypointDependencies) {
+      this.entrypointDependencyGraph.setEntrypointDependencies(entrypointPath, entrypointDependencies);
+    }
+  }
+  stop() {
+    this.entrypointRegistrations.clear();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
+  }
+}
+export {
+  SharedHmrManager
+};

package/src/adapters/shared/static-preview-host.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export interface StaticPreviewHost {
+    start(options: StaticPreviewHostStartOptions): Promise<number | null>;
+    stop(force?: boolean): Promise<void>;
+}
+export interface StaticPreviewHostStartOptions {
+    appConfig: EcoPagesAppConfig;
+    hostname: string;
+    port: number;
+}

package/src/build/build-adapter.js

@@ -213,7 +213,15 @@ class BunBuildAdapter {
     if (entryExtension === ".toml") {
       return ".toml";
     }
-    return options.format === "cjs" || options.format === "esm" ? ".js" : ".js";
+    if (options.target !== "browser") {
+      if (options.format === "cjs") {
+        return ".cjs";
+      }
+      if (options.format === "esm") {
+        return ".mjs";
+      }
+    }
+    return ".js";
   }
   resolveConcreteOutputPath(outputPath) {
     if (fs.existsSync(outputPath)) {
@@ -570,6 +578,9 @@ async function collectConfiguredAppBuildManifestContributions(appConfig) {
   };
 }
 async function setupAppRuntimePlugins(options) {
+  for (const loader of options.appConfig.loaders.values()) {
+    options.onRuntimePlugin?.(loader);
+  }
   for (const processor of options.appConfig.processors.values()) {
     await processor.setup();
     if (processor.plugins) {

package/src/build/esbuild-build-adapter.d.ts

@@ -9,6 +9,7 @@ export declare const ESBUILD_ADAPTER_BRAND: unique symbol;
 export declare class EsbuildBuildAdapter implements BuildAdapter {
     readonly ownership: "bun-native";
     readonly [ESBUILD_ADAPTER_BRAND] = true;
+    private getJavaScriptOutExtension;
     private collectWorkspaceNodePaths;
     private getFallbackNodePaths;
     private rewriteAliasedRuntimeSpecifiers;

package/src/build/esbuild-build-adapter.js

@@ -33,6 +33,18 @@ const ESBUILD_ADAPTER_BRAND = /* @__PURE__ */ Symbol.for("EsbuildBuildAdapter");
 class EsbuildBuildAdapter {
   ownership = "bun-native";
   [ESBUILD_ADAPTER_BRAND] = true;
+  getJavaScriptOutExtension(options) {
+    if (options.target === "browser") {
+      return void 0;
+    }
+    if (options.format === "cjs") {
+      return ".cjs";
+    }
+    if (options.format === "esm") {
+      return ".mjs";
+    }
+    return void 0;
+  }
   collectWorkspaceNodePaths(scanRoot, maxDepth = 3) {
     const normalizedRoot = path.resolve(scanRoot);
     const cached = workspaceNodePathsCache.get(normalizedRoot);
@@ -364,6 +376,7 @@ class EsbuildBuildAdapter {
       external: options.external,
       ...options.target !== "browser" && options.externalPackages !== false ? { packages: "external" } : {},
       target: transpileTarget,
+      ...this.getJavaScriptOutExtension(options) ? { outExtension: { ".js": this.getJavaScriptOutExtension(options) } } : {},
       metafile: true,
       write: true,
       plugins: esbuildPlugins,

package/src/hmr/strategies/js-hmr-strategy.js

@@ -36,10 +36,6 @@ class JsHmrStrategy extends HmrStrategy {
     if (watchedFiles.has(filePath)) {
       return true;
     }
-    const entrypointDependencyGraph = this.context.getEntrypointDependencyGraph();
-    if (entrypointDependencyGraph.supportsSelectiveInvalidation()) {
-      return entrypointDependencyGraph.getDependencyEntrypoints(filePath).size > 0;
-    }
     return true;
   }
   /**

package/src/plugins/integration-plugin.d.ts

@@ -8,6 +8,8 @@ import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-p
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
 export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
+export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
  *
@@ -84,7 +86,10 @@ type RendererClass<C> = new (options: {
  *
  * Core owns lifecycle ordering. Integrations declare contributions through the
  * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
- * those hooks run.
+ * those hooks run. For page-browser and document shaping, integrations should
+ * prefer the contribution contracts re-exported from this module:
+ * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
+ * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
  */
 export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;

package/src/route-renderer/orchestration/integration-renderer.d.ts

@@ -4,9 +4,10 @@
  * @module
  */
 import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
-import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, ForeignSubtreeRenderPayload, EcoComponent, EcoComponentDependencies, EcoPageFile, EcoPagesElement, BaseIntegrationContext, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult } from '../../types/public-types.js';
 import { type AssetProcessingService, type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
 import { HtmlTransformerService } from '../../services/html/html-transformer.service.js';
+import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 import { HttpError } from '../../errors/http-error.js';
 import { DependencyResolverService } from '../page-loading/dependency-resolver.js';
 import { PageModuleLoaderService } from '../page-loading/page-module-loader.js';
@@ -33,6 +34,12 @@ export interface RenderToResponseContext {
     status?: number;
     headers?: HeadersInit;
 }
+export type HtmlDocumentContributionContext<C = EcoPagesElement> = {
+    renderOptions?: IntegrationRendererRenderOptions<C>;
+    partial?: boolean;
+};
+export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../../types/public-types.js';
+export type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
 /**
  * The IntegrationRenderer class is an abstract class that provides a base for rendering integration-specific components in the EcoPages framework.
  * It handles the import of page files, collection of dependencies, and preparation of render options.
@@ -123,6 +130,8 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * @returns Resolved processed assets
      */
     protected prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+    protected resolvePageBrowserGraphForFile(filePath: string): Promise<PageBrowserGraphResult | undefined>;
+    protected mergePageBrowserGraphIntoPagePackage(pageBrowserGraph?: PageBrowserGraphResult): PageBrowserGraphResult | undefined;
     /**
      * Merges component-scoped assets into the active HTML transformer state.
      *
@@ -329,14 +338,10 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected createRouteRenderOrchestratorAdapter(): RouteRenderOrchestratorAdapter<C>;
     protected resolveRouteRenderInputs(routeOptions: RouteRendererOptions): Promise<RouteRenderOrchestratorResolvedInputs>;
-    protected resolveRouteAssets(input: {
-        routeOptions: RouteRendererOptions;
+    protected resolveRouteDependencies(input: {
         components: (EcoComponent | Partial<EcoComponent>)[];
     }): Promise<{
         resolvedDependencies: ProcessedAsset[];
-        pageBrowserGraph?: {
-            assets: ProcessedAsset[];
-        };
     }>;
     protected resolveRoutePageComponentRender(input: {
         Page: EcoComponent;
@@ -346,7 +351,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
     }): Promise<ComponentRenderResult | undefined>;
     protected renderRouteBody(renderOptions: IntegrationRendererRenderOptions<C>): Promise<RouteRendererBody>;
     protected getRouteHtmlFinalization(renderOptions: IntegrationRendererRenderOptions<C>): RouteHtmlFinalization;
-    protected transformRouteResponse(response: Response): Promise<RouteRendererBody>;
+    protected transformRouteResponse(response: Response, htmlContributions?: HtmlDocumentContribution[]): Promise<RouteRendererBody>;
     /**
      * Prepares the render options for the integration renderer.
      * It imports the page file, collects dependencies, and prepares the render options.
@@ -399,6 +404,7 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
         componentRootAttributes?: Record<string, string>;
         documentAttributes?: Record<string, string>;
         transformHtml?: boolean;
+        htmlContributions?: HtmlDocumentContribution[];
     }): Promise<string>;
     /**
      * Returns document-level attributes to stamp onto the rendered `<html>` tag.
@@ -407,6 +413,16 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      * other runtime coordination markers without relying on script sniffing.
      */
     protected getDocumentAttributes(_renderOptions: IntegrationRendererRenderOptions<C>): Record<string, string> | undefined;
+    /**
+     * 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.
+     */
+    protected getHtmlDocumentContributions(_options: HtmlDocumentContributionContext<C>): HtmlDocumentContribution[] | undefined;
     /**
      * Returns a renderer instance for a given integration name.
      *
@@ -486,15 +502,17 @@ export declare abstract class IntegrationRenderer<C = EcoPagesElement> {
      */
     protected getRootTagName(html: string): string | undefined;
     /**
-     * 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.
      */
-    protected buildPageBrowserGraph(_file: string): Promise<{
-        assets: ProcessedAsset[];
-    } | undefined>;
+    protected collectPageBrowserGraphContribution(_context: PageBrowserGraphContributionContext): Promise<PageBrowserGraphContribution | undefined>;
     /**
      * Creates the per-render foreign-child runtime adopted by the shared component
      * render context.