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

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

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileSystem } from "@ecopages/file-system";
+import { getAppBuildAdapter } from "../../../../../build/build-adapter.js";
+import { BaseScriptProcessor } from "../base/base-script-processor.js";
+class NodeModuleScriptProcessor extends BaseScriptProcessor {
+  async process(dep) {
+    const modulePath = this.resolveModulePath(dep.importPath, this.appConfig.rootDir);
+    const moduleName = path.basename(modulePath);
+    const filename = dep.name ?? `nm-${moduleName}`;
+    const configHash = this.generateHash(
+      JSON.stringify({ inline: dep.inline, minify: !dep.inline && this.isProduction, opts: dep.bundleOptions })
+    );
+    const cachekey = `${this.buildCacheKey(filename, this.generateHash(modulePath), dep)}:${configHash}`;
+    return this.getOrProcess(cachekey, async () => {
+      if (dep.inline) {
+        const content = fileSystem.readFileAsBuffer(modulePath).toString();
+        return {
+          content,
+          kind: dep.kind,
+          position: dep.position,
+          attributes: dep.attributes,
+          inline: true,
+          excludeFromHtml: dep.excludeFromHtml,
+          packageRole: dep.packageRole,
+          bundledSourceFilepaths: dep.bundledSourceFilepaths
+        };
+      }
+      const outdir = path.join(this.getAssetsDir(), "vendors");
+      const bundlerOptions = this.getBundlerOptions(dep);
+      const filePath = await this.bundleScript({
+        entrypoint: modulePath,
+        outdir,
+        minify: this.isProduction,
+        naming: bundlerOptions.naming ?? (dep.name ? `${dep.name}-[hash].[ext]` : "[name]-[hash].[ext]"),
+        ...bundlerOptions
+      });
+      return {
+        filepath: filePath,
+        kind: dep.kind,
+        position: dep.position,
+        attributes: dep.attributes,
+        inline: dep.inline,
+        excludeFromHtml: dep.excludeFromHtml,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
+      };
+    });
+  }
+  /**
+   * Resolves a node-module script entry from the current app boundary.
+   *
+   * @remarks
+   * The build adapter remains the primary resolution surface because Bun/native
+   * host-owned builds may have a more accurate view of aliases and package
+   * ownership than core does. The local fallback only runs when that adapter
+   * resolution is unavailable.
+   */
+  resolveModulePath(importPath, rootDir) {
+    if (path.isAbsolute(importPath) && fileSystem.exists(importPath)) {
+      return importPath;
+    }
+    try {
+      return getAppBuildAdapter(this.appConfig).resolve(importPath, rootDir);
+    } catch {
+      return this.resolveModulePathFallback(importPath, rootDir);
+    }
+  }
+  /**
+   * Resolves browser-owned script specifiers without relying on CommonJS resolution.
+   *
+   * @remarks
+   * This path intentionally stays ESM-first because these assets are emitted as
+   * browser scripts. We first ask Node's ESM resolver to evaluate the package
+   * export map from the app boundary. If that still fails, we fall back to a
+   * bounded filesystem probe so direct file installs and package subpaths like
+   * `pkg/client/entry` still resolve when the export map does not cover them.
+   */
+  resolveModulePathFallback(importPath, rootDir, maxDepth = 5) {
+    try {
+      return fileURLToPath(
+        import.meta.resolve(importPath, pathToFileURL(path.join(rootDir, "package.json")).href)
+      );
+    } catch {
+    }
+    let currentDir = rootDir;
+    let remainingDepth = maxDepth;
+    while (remainingDepth >= 0) {
+      for (const candidatePath of this.getFallbackCandidatePaths(currentDir, importPath)) {
+        if (fileSystem.exists(candidatePath)) {
+          return candidatePath;
+        }
+      }
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        break;
+      }
+      currentDir = parentDir;
+      remainingDepth -= 1;
+    }
+    throw new Error(`Could not resolve module '${importPath}' from '${rootDir}'`);
+  }
+  /**
+   * Returns the file candidates we accept during the final literal filesystem probe.
+   *
+   * @remarks
+   * This is intentionally small and browser-entry-oriented: direct files, common
+   * JS extensions, and `index.*` entrypoints. If a package needs anything more
+   * exotic, it should resolve through the adapter or ESM export-map path above.
+   */
+  getFallbackCandidatePaths(rootDir, importPath) {
+    const moduleBasePath = path.join(rootDir, "node_modules", importPath);
+    return [
+      moduleBasePath,
+      `${moduleBasePath}.js`,
+      `${moduleBasePath}.mjs`,
+      `${moduleBasePath}.cjs`,
+      path.join(moduleBasePath, "index.js"),
+      path.join(moduleBasePath, "index.mjs"),
+      path.join(moduleBasePath, "index.cjs")
+    ];
+  }
+}
+export {
+  NodeModuleScriptProcessor
+};

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/stylesheet/content-stylesheet.processor.d.ts

@@ -1,5 +1,8 @@
-import type { ContentStylesheetAsset, ProcessedAsset } from '../../assets.types';
-import { BaseProcessor } from '../base/base-processor';
+import type { ContentStylesheetAsset, ProcessedAsset } from '../../assets.types.js';
+import { BaseProcessor } from '../base/base-processor.js';
 export declare class ContentStylesheetProcessor extends BaseProcessor<ContentStylesheetAsset> {
+    private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS;
+    private isProcessableStylesheet;
+    private applyStylesheetProcessors;
     process(dep: ContentStylesheetAsset): Promise<ProcessedAsset>;
 }

package/src/services/assets/asset-processing-service/processors/stylesheet/content-stylesheet.processor.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { BaseProcessor } from "../base/base-processor.js";
+class ContentStylesheetProcessor extends BaseProcessor {
+  static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
+  isProcessableStylesheet(filepath) {
+    return ContentStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+  }
+  async applyStylesheetProcessors(content, filepath) {
+    if (!this.isProcessableStylesheet(filepath)) {
+      return content;
+    }
+    let transformedContent = content;
+    const processors = this.appConfig.processors ? Array.from(this.appConfig.processors.values()) : [];
+    for (const processor of processors) {
+      const hasCapabilities = processor.getAssetCapabilities().length > 0;
+      const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
+      if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes("postcss"))) {
+        continue;
+      }
+      if (!processor.matchesFileFilter(filepath)) {
+        continue;
+      }
+      const result = await processor.process(transformedContent, filepath);
+      if (typeof result === "string") {
+        transformedContent = result;
+        continue;
+      }
+      if (result instanceof Buffer) {
+        transformedContent = result.toString();
+      }
+    }
+    return transformedContent;
+  }
+  async process(dep) {
+    const virtualFilepath = path.join(this.appConfig.absolutePaths.distDir, "styles", "page-bundle.css");
+    const processedContent = await this.applyStylesheetProcessors(dep.content, virtualFilepath);
+    const hash = this.generateHash(processedContent);
+    const filename = `style-${hash}.css`;
+    const cachekey = this.buildCacheKey(filename, hash, dep);
+    return this.getOrProcess(cachekey, () => {
+      const filepath = path.join(this.getAssetsDir(), "styles", filename);
+      if (!dep.inline) fileSystem.write(filepath, processedContent);
+      return {
+        filepath: dep.inline ? void 0 : filepath,
+        content: dep.inline ? processedContent : void 0,
+        kind: "stylesheet",
+        position: dep.position,
+        attributes: dep.attributes,
+        inline: dep.inline,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
+      };
+    });
+  }
+}
+export {
+  ContentStylesheetProcessor
+};

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/stylesheet/file-stylesheet.processor.d.ts

@@ -1,5 +1,5 @@
-import type { FileStylesheetAsset, ProcessedAsset } from '../../assets.types';
-import { BaseProcessor } from '../base/base-processor';
+import type { FileStylesheetAsset, ProcessedAsset } from '../../assets.types.js';
+import { BaseProcessor } from '../base/base-processor.js';
 export declare class FileStylesheetProcessor extends BaseProcessor<FileStylesheetAsset> {
     private static readonly PROCESSABLE_STYLESHEET_EXTENSIONS;
     getStyleContent: (srcUrl: string) => Buffer;

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/stylesheet/file-stylesheet.processor.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { BaseProcessor } from "../base/base-processor";
+import { BaseProcessor } from "../base/base-processor.js";
 class FileStylesheetProcessor extends BaseProcessor {
   static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
   getStyleContent = (srcUrl) => {
@@ -41,7 +41,10 @@ class FileStylesheetProcessor extends BaseProcessor {
     const hash = this.generateHash(processedContent);
     const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
     return this.getOrProcess(cachekey, () => {
-      const filepath = path.join(this.getAssetsDir(), path.relative(this.appConfig.srcDir, dep.filepath));
+      const filepath = path.join(
+        this.getAssetsDir(),
+        path.relative(this.appConfig.absolutePaths.srcDir, dep.filepath)
+      );
       const outputBuffer = Buffer.from(processedContent);
       if (!dep.inline) {
         fileSystem.ensureDir(path.dirname(filepath));
@@ -49,11 +52,14 @@ class FileStylesheetProcessor extends BaseProcessor {
       }
       return {
         filepath,
+        sourceFilepath: dep.filepath,
         content: dep.inline ? processedContent : void 0,
         kind: "stylesheet",
         position: dep.position,
         attributes: dep.attributes,
-        inline: dep.inline
+        inline: dep.inline,
+        packageRole: dep.packageRole,
+        bundledSourceFilepaths: dep.bundledSourceFilepaths
       };
     });
   }

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

@@ -0,0 +1,18 @@
+import type { AssetProcessor } from './processor.interface.js';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+type ProcessUngroupedDependencyOptions = {
+    dep: AssetDefinition;
+    key: string;
+    depKey: string;
+    getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
+    getProcessor: (dep: AssetDefinition) => AssetProcessor | undefined;
+    resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined;
+    setCachedAsset: (dep: AssetDefinition, depKey: string, processed: ProcessedAsset) => void;
+    logMissingProcessor: (dep: AssetDefinition) => void;
+    logMissingFile: (dep: AssetDefinition & {
+        filepath: string;
+    }) => void;
+    logProcessingError: (dep: AssetDefinition, error: unknown) => void;
+};
+export declare function processUngroupedDependency(options: ProcessUngroupedDependencyOptions): Promise<ProcessedAsset | null>;
+export {};

package/src/services/assets/asset-processing-service/ungrouped-dependency-processing.js

@@ -0,0 +1,45 @@
+import { fileSystem } from "@ecopages/file-system";
+async function processUngroupedDependency(options) {
+  const {
+    dep,
+    key,
+    depKey,
+    getCachedAsset,
+    getProcessor,
+    resolveProcessedAssetSrcUrl,
+    setCachedAsset,
+    logMissingProcessor,
+    logMissingFile,
+    logProcessingError
+  } = options;
+  const cached = getCachedAsset(dep, depKey);
+  if (cached) {
+    return { key, ...cached };
+  }
+  const processor = getProcessor(dep);
+  if (!processor) {
+    logMissingProcessor(dep);
+    return null;
+  }
+  if (dep.source === "file" && "filepath" in dep && !fileSystem.exists(dep.filepath)) {
+    logMissingFile(dep);
+    return null;
+  }
+  try {
+    const processed = await processor.process(dep);
+    const srcUrl = resolveProcessedAssetSrcUrl(processed);
+    const processedWithKey = {
+      key,
+      ...processed,
+      srcUrl
+    };
+    setCachedAsset(dep, depKey, processedWithKey);
+    return processedWithKey;
+  } catch (error) {
+    logProcessingError(dep, error);
+    return null;
+  }
+}
+export {
+  processUngroupedDependency
+};

package/src/services/assets/browser-bundle.service.d.ts

@@ -0,0 +1,73 @@
+import type { BuildResult, BuildTranspileProfile } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type BrowserBundleOptions = {
+    entrypoints: string[];
+    outdir?: string;
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
+    profile: BuildTranspileProfile;
+    excludeAppBuildPlugins?: string[];
+};
+type BrowserBundleGroupedOptions = {
+    outdir?: string;
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
+    profile: BuildTranspileProfile;
+    excludeAppBuildPlugins?: string[];
+};
+export interface BrowserBundleExecutor {
+    bundle(options: BrowserBundleOptions): Promise<BuildResult>;
+}
+export type BrowserBundleGroupedEntry = {
+    entrypoint: string;
+    entryName: string;
+};
+/**
+ * App-owned boundary for browser-oriented bundle work.
+ *
+ * @remarks
+ * This service owns the shared browser transpile defaults and ensures browser
+ * builds always run through the app-owned executor rather than direct backend
+ * calls scattered across HMR and asset processing paths.
+ */
+export declare class BrowserBundleService implements BrowserBundleExecutor {
+    private readonly appConfig;
+    /**
+     * Creates the browser bundle boundary for one finalized app instance.
+     */
+    constructor(appConfig: EcoPagesAppConfig);
+    /**
+     * Runs one browser-targeted build through the app-owned executor.
+     *
+     * @remarks
+     * Browser defaults and app-owned browser build plugins are applied here so HMR
+     * and runtime asset generation do not have to recreate that policy at each call
+     * site.
+     */
+    bundle(options: BrowserBundleOptions): Promise<BuildResult>;
+    bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;
+}
+export {};

package/src/services/assets/browser-bundle.service.js

@@ -0,0 +1,41 @@
+import { getAppBrowserBuildPlugins, getAppBuildExecutor, getAppTranspileOptions } from "../../build/build-adapter.js";
+import { mergeEcoBuildPlugins } from "../../build/build-manifest.js";
+class BrowserBundleService {
+  appConfig;
+  /**
+   * Creates the browser bundle boundary for one finalized app instance.
+   */
+  constructor(appConfig) {
+    this.appConfig = appConfig;
+  }
+  /**
+   * Runs one browser-targeted build through the app-owned executor.
+   *
+   * @remarks
+   * Browser defaults and app-owned browser build plugins are applied here so HMR
+   * and runtime asset generation do not have to recreate that policy at each call
+   * site.
+   */
+  async bundle(options) {
+    const { profile, excludeAppBuildPlugins, plugins, ...rawBuildOptions } = options;
+    const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
+    const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0 ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name)) : appBrowserPlugins;
+    const request = {
+      ...rawBuildOptions,
+      entrypoints: options.entrypoints,
+      ...getAppTranspileOptions(this.appConfig, profile),
+      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins)
+    };
+    return await getAppBuildExecutor(this.appConfig).build(request);
+  }
+  async bundleGroupedEntries(entries, options) {
+    const request = {
+      ...options,
+      entrypoints: entries.map((entry) => entry.entrypoint)
+    };
+    return this.bundle(request);
+  }
+}
+export {
+  BrowserBundleService
+};

package/src/services/{page-request-cache-coordinator.service.d.ts → cache/page-request-cache-coordinator.service.d.ts}

@@ -1,5 +1,5 @@
-import { type PageCacheService } from './cache/page-cache-service.js';
-import type { CacheStrategy, RenderResult } from './cache/cache.types.js';
+import { type PageCacheService } from './page-cache-service.js';
+import type { CacheStrategy, RenderResult } from './cache.types.js';
 /**
  * Coordinates request-time page caching concerns around one render invocation.
  *

package/src/services/{page-request-cache-coordinator.service.js → cache/page-request-cache-coordinator.service.js}

@@ -1,5 +1,7 @@
-import { getCacheControlHeader } from "./cache/page-cache-service.js";
+import { getCacheControlHeader } from "./page-cache-service.js";
 class PageRequestCacheCoordinator {
+  cacheService;
+  defaultCacheStrategy;
   constructor(cacheService, defaultCacheStrategy) {
     this.cacheService = cacheService;
     this.defaultCacheStrategy = defaultCacheStrategy;

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

@@ -0,0 +1,40 @@
+export type HtmlRewriterElement = {
+    prepend(content: string, options?: {
+        html?: boolean;
+    }): void;
+    append(content: string, options?: {
+        html?: boolean;
+    }): void;
+};
+export type HtmlRewriterRuntime = {
+    on(selector: 'head' | 'body', handler: {
+        element: (element: HtmlRewriterElement) => void;
+    }): HtmlRewriterRuntime;
+    transform(response: Response): Response;
+};
+export type HtmlRewriterConstructor = new () => HtmlRewriterRuntime;
+export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
+export interface HtmlRewriterProvider {
+    createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+    setMode(mode: HtmlRewriterMode): void;
+}
+export interface HtmlRewriterLogger {
+    warn(message: string): void;
+}
+export interface DefaultHtmlRewriterProviderOptions {
+    mode?: HtmlRewriterMode;
+    logger?: HtmlRewriterLogger;
+    getNativeHtmlRewriter?: () => HtmlRewriterConstructor | undefined;
+    loadWorkerToolsHtmlRewriter?: () => Promise<HtmlRewriterConstructor | null>;
+}
+export declare class DefaultHtmlRewriterProvider implements HtmlRewriterProvider {
+    private htmlRewriterConstructorPromise?;
+    private htmlRewriterMode;
+    private logger;
+    private getNativeHtmlRewriter;
+    private loadWorkerToolsHtmlRewriter;
+    constructor(options?: DefaultHtmlRewriterProviderOptions);
+    setMode(mode: HtmlRewriterMode): void;
+    createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+    private resolveHtmlRewriterConstructor;
+}

package/src/services/html/html-rewriter-provider.service.js

@@ -0,0 +1,68 @@
+import { appLogger } from "../../global/app-logger.js";
+class DefaultHtmlRewriterProvider {
+  htmlRewriterConstructorPromise;
+  htmlRewriterMode;
+  logger;
+  getNativeHtmlRewriter;
+  loadWorkerToolsHtmlRewriter;
+  constructor(options = {}) {
+    this.htmlRewriterMode = options.mode ?? "auto";
+    this.logger = options.logger ?? appLogger;
+    this.getNativeHtmlRewriter = options.getNativeHtmlRewriter ?? (() => globalThis.HTMLRewriter);
+    this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
+  }
+  setMode(mode) {
+    this.htmlRewriterMode = mode;
+    this.htmlRewriterConstructorPromise = void 0;
+  }
+  async createHtmlRewriter() {
+    const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
+    return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
+  }
+  async resolveHtmlRewriterConstructor() {
+    if (!this.htmlRewriterConstructorPromise) {
+      const mode = this.htmlRewriterMode;
+      const RuntimeHtmlRewriter = this.getNativeHtmlRewriter();
+      if (mode === "fallback") {
+        this.htmlRewriterConstructorPromise = Promise.resolve(null);
+      } else if (mode === "native") {
+        if (RuntimeHtmlRewriter) {
+          this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+        } else {
+          this.logger.warn(
+            "[HtmlTransformerService] Native HTMLRewriter was forced but is unavailable, falling back to string injection."
+          );
+          this.htmlRewriterConstructorPromise = Promise.resolve(null);
+        }
+      } else if (mode === "auto" && RuntimeHtmlRewriter) {
+        this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+      } else {
+        this.htmlRewriterConstructorPromise = this.loadWorkerToolsHtmlRewriter();
+      }
+    }
+    return this.htmlRewriterConstructorPromise;
+  }
+}
+async function loadWorkerToolsHtmlRewriter() {
+  try {
+    const module = await import("@worker-tools/html-rewriter/base64");
+    return module.HTMLRewriter;
+  } catch (primaryError) {
+    try {
+      const runtimeLocalModule = await import(
+        /* @vite-ignore */
+        new URL("../node_modules/@worker-tools/html-rewriter/base64.js", import.meta.url).href
+      );
+      return runtimeLocalModule.HTMLRewriter;
+    } catch {
+      const message = primaryError instanceof Error ? primaryError.message : String(primaryError);
+      appLogger.warn(
+        `[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`
+      );
+      return null;
+    }
+  }
+}
+export {
+  DefaultHtmlRewriterProvider
+};

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

@@ -0,0 +1,96 @@
+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;
+}
+export declare class HtmlTransformerService {
+    private processedDependencies;
+    private pagePackage?;
+    private htmlRewriterProvider;
+    constructor(options?: HtmlTransformerServiceOptions);
+    /**
+     * Overrides the HTML rewriter runtime selection.
+     *
+     * This is intended for internal/runtime tests that need deterministic
+     * selection between native, worker-tools, and string fallback behavior.
+     *
+     * @param mode Requested runtime selection strategy.
+     */
+    setHtmlRewriterMode(mode: HtmlRewriterMode): void;
+    private formatAttributes;
+    private generateScriptTag;
+    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.
+     */
+    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    /**
+     * Replaces the current structured page package used during HTML finalization.
+     */
+    setPagePackage(pagePackage: PagePackageResult): void;
+    /**
+     * Returns the processed dependencies queued for the next transform pass.
+     */
+    getProcessedDependencies(): ProcessedAsset[];
+    /**
+     * Returns the structured page package queued for the next transform pass.
+     */
+    getPagePackage(): PagePackageResult | undefined;
+    /**
+     * Applies attributes to the opening `<html>` tag when present.
+     */
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element nested directly under `<body>`.
+     */
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element in a fragment or full-document HTML
+     * string.
+     */
+    applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Removes duplicate processed assets while preserving first-seen order.
+     *
+     * @remarks
+     * Dedupe keys include structural asset fields and HTML attributes so repeated
+     * orchestration passes can merge assets safely without collapsing distinct tag
+     * variants.
+     */
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+    /**
+     * Injects the currently processed dependencies into an HTML response.
+     *
+     * @remarks
+     * Native or worker-tools HTML rewriter support is preferred when available. A
+     * string-based fallback remains in place for runtimes that cannot provide one
+     * of those rewriter implementations.
+     */
+    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.
+     */
+    private buildAttributeString;
+}