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

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

@@ -1,14 +1,37 @@
-import type { EcoBuildPlugin } from '../build/build-types';
-import type { EcoPagesAppConfig, IHmrManager } from '../internal-types';
-import type { HmrStrategy } from '../hmr/hmr-strategy';
-import type { EcoComponent, EcoPagesElement } from '../public-types';
-import type { IntegrationRenderer } from '../route-renderer/integration-renderer';
-import { AssetProcessingService } from '../services/asset-processing-service/asset-processing.service';
-import type { AssetDefinition, ProcessedAsset } from '../services/asset-processing-service/assets.types';
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import { type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
+import type { HmrStrategy } from '../hmr/hmr-strategy.js';
+import type { EcoPagesElement } from '../types/public-types.js';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
+import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
+import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+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.
+ *
+ * Ecopages keeps one heterogeneous integration list, while each plugin and
+ * renderer still owns its framework-specific render payload type internally.
+ */
+export type AnyIntegrationPlugin = IntegrationPlugin<unknown>;
 export declare const INTEGRATION_PLUGIN_ERRORS: {
     readonly NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config";
     readonly NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service";
 };
+export declare function mergeIntegrationOptions<TDefaults, TOverrides>(defaults: TDefaults, overrides: TOverrides): TDefaults & TOverrides;
+export declare function assertIntegrationInvariant(condition: boolean, message?: string): asserts condition;
+/**
+ * Base configuration shared by all integration plugins.
+ *
+ * @remarks
+ * Integrations declare their file ownership, optional runtime requirements, and
+ * any global assets or build-time contributions here. Runtime-only side effects
+ * belong in `setup()` rather than the constructor.
+ */
 export interface IntegrationPluginConfig {
     /**
      * The name of the integration plugin.
@@ -31,29 +54,51 @@ export interface IntegrationPluginConfig {
      * @default 'render'
      */
     staticBuildStep?: 'render' | 'fetch';
+    /**
+     * Declares runtime-specific requirements that must be satisfied before the
+     * app can start with this integration enabled.
+     */
+    runtimeCapability?: RuntimeCapabilityDeclaration;
+    /**
+     * JSX import source owned by this integration.
+     *
+     * @remarks
+     * This is primarily used by mixed-JSX flows where host-owned browser bundles
+     * need to preserve the correct JSX runtime for files claimed by the
+     * integration.
+     */
+    jsxImportSource?: string;
 }
-/**
- * Metadata used by integration-owned boundary policy.
- *
- * This payload describes the currently active integration pass together with the
- * target component boundary being entered.
- */
-export type ComponentBoundaryPolicyInput = {
-    currentIntegration: string;
-    targetIntegration?: string;
-    component: EcoComponent;
-};
 type RendererClass<C> = new (options: {
     appConfig: EcoPagesAppConfig;
     assetProcessingService: AssetProcessingService;
     resolvedIntegrationDependencies: ProcessedAsset[];
+    rendererModules?: unknown;
     runtimeOrigin: string;
 }) => IntegrationRenderer<C>;
+/**
+ * Base class for framework integrations.
+ *
+ * @remarks
+ * An integration owns three main concerns:
+ * - which file extensions it claims
+ * - which renderer class turns those files into HTML
+ * - which build-time or runtime contributions must be registered for that framework
+ *
+ * Core owns lifecycle ordering. Integrations declare contributions through the
+ * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
+ * 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;
     readonly extensions: string[];
     abstract renderer: RendererClass<C>;
     readonly staticBuildStep: 'render' | 'fetch';
+    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
+    readonly jsxImportSource?: string;
     protected integrationDependencies: AssetDefinition[];
     protected resolvedIntegrationDependencies: ProcessedAsset[];
     protected options?: Record<string, unknown>;
@@ -62,8 +107,42 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     protected hmrManager?: IHmrManager;
     runtimeOrigin: string;
     get plugins(): EcoBuildPlugin[];
+    /**
+     * Returns build plugins that should only apply to browser-oriented bundles.
+     *
+     * @remarks
+     * Browser-only transforms such as runtime import aliasing belong here so they
+     * do not affect server bundles or static-page module generation.
+     */
+    get browserBuildPlugins(): EcoBuildPlugin[];
+    /**
+     * Returns shared browser runtime asset declarations owned by this integration.
+     *
+     * @remarks
+     * Core seals these declarations into the app build manifest so app-owned browser
+     * bundle paths can rewrite manifest-owned imports even when a specific build
+     * request does not install an integration-local runtime rewrite plugin.
+     */
+    get browserRuntimeManifest(): BrowserRuntimeManifest;
+    /**
+     * Creates the integration with static declaration-only configuration.
+     *
+     * @remarks
+     * Constructors are expected to stay side-effect free. Build-manifest
+     * contributions belong in `prepareBuildContributions()` and runtime-only setup
+     * belongs in `setup()`.
+     */
     constructor(config: IntegrationPluginConfig);
+    /**
+     * Attaches the finalized app config to the integration.
+     *
+     * Core calls this during config finalization before runtime setup so the
+     * integration can resolve asset paths and other app-owned services later.
+     */
     setConfig(appConfig: EcoPagesAppConfig): void;
+    /**
+     * Records the runtime origin used for page-module loading and renderer setup.
+     */
     setRuntimeOrigin(runtimeOrigin: string): void;
     /**
      * Returns an HMR strategy for this integration, if applicable.
@@ -75,28 +154,77 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * ```typescript
      * getHmrStrategy(): HmrStrategy {
      *   const context = this.hmrManager!.getDefaultContext();
-     *   return new ReactHmrStrategy(context);
+     *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeManifest });
      * }
      * ```
      */
     getHmrStrategy?(): HmrStrategy | undefined;
+    /**
+     * Attaches the shared HMR manager and registers integration-owned development hooks.
+     *
+     * @remarks
+     * The default implementation registers the optional integration HMR strategy.
+     * Integrations should override this only when they need to extend that shared
+     * behavior rather than replace it.
+     */
     setHmrManager(hmrManager: IHmrManager): void;
+    /**
+     * Creates the asset-processing service used for global integration dependencies.
+     */
     initializeAssetDefinitionService(): void;
+    /**
+     * Returns processed global assets resolved during `setup()`.
+     */
     getResolvedIntegrationDependencies(): ProcessedAsset[];
-    initializeRenderer(): IntegrationRenderer<C>;
     /**
-     * Declares whether a component boundary targeting this integration should be
-     * deferred through the marker pipeline.
+     * Creates the shared renderer options owned by core lifecycle setup.
+     */
+    protected createRendererOptions(options?: {
+        rendererModules?: unknown;
+    }): {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies: ProcessedAsset[];
+        rendererModules: unknown;
+        runtimeOrigin: string;
+    };
+    /**
+     * Attaches runtime-only services after a renderer instance has been created.
+     */
+    protected attachRendererRuntimeServices<T extends IntegrationRenderer<C>>(renderer: T): T;
+    /**
+     * Instantiates the integration renderer with app-owned services.
      *
-     * The default implementation never defers. Integrations that require deferred
-     * subtree rendering should override this method and return `true` when their
-     * boundary must be resolved during the marker graph stage.
+     * @remarks
+     * Renderers are cheap runtime objects. They receive the finalized app config,
+     * a fresh asset-processing service, integration-global processed assets, and
+     * any renderer module context supplied by the active runtime.
+            renderer.name ||= this.name;
+     */
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): IntegrationRenderer<C>;
+    /**
+     * Prepares build-facing contributions before the app build manifest is sealed.
      *
-     * @param input Boundary metadata for the current render pass.
-     * @returns `true` when the boundary should be deferred; otherwise `false`.
+     * @remarks
+     * Integrations can override this when runtime or build plugin declarations must
+     * be materialized ahead of runtime startup. Runtime-only side effects stay in
+     * `setup()`.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Performs runtime-only integration setup after config build has already
+     * sealed manifest contributions.
      */
-    shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
     setup(): Promise<void>;
+    /**
+     * Releases runtime resources owned by the integration.
+     *
+     * @remarks
+     * Most integrations do not need custom teardown. Override this only for
+     * explicit cleanup such as watchers, compiler handles, or runtime registries
+     * that outlive individual requests.
+     */
     teardown(): Promise<void>;
 }
-export {};

package/src/plugins/integration-plugin.js

@@ -1,12 +1,23 @@
-import { AssetProcessingService } from "../services/asset-processing-service/asset-processing.service";
+import { createBrowserRuntimeManifest } from "../build/browser-runtime-manifest.js";
+import { AssetProcessingService } from "../services/assets/asset-processing-service/asset-processing.service.js";
+import { deepMerge } from "../utils/deep-merge.js";
+import { invariant } from "../utils/invariant.js";
 const INTEGRATION_PLUGIN_ERRORS = {
   NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config",
   NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service"
 };
+function mergeIntegrationOptions(defaults, overrides) {
+  return deepMerge(defaults, overrides);
+}
+function assertIntegrationInvariant(condition, message) {
+  invariant(condition, message);
+}
 class IntegrationPlugin {
   name;
   extensions;
   staticBuildStep;
+  runtimeCapability;
+  jsxImportSource;
   integrationDependencies;
   resolvedIntegrationDependencies = [];
   options;
@@ -16,19 +27,67 @@ class IntegrationPlugin {
   get plugins() {
     return [];
   }
+  /**
+   * Returns build plugins that should only apply to browser-oriented bundles.
+   *
+   * @remarks
+   * Browser-only transforms such as runtime import aliasing belong here so they
+   * do not affect server bundles or static-page module generation.
+   */
+  get browserBuildPlugins() {
+    return [];
+  }
+  /**
+   * Returns shared browser runtime asset declarations owned by this integration.
+   *
+   * @remarks
+   * Core seals these declarations into the app build manifest so app-owned browser
+   * bundle paths can rewrite manifest-owned imports even when a specific build
+   * request does not install an integration-local runtime rewrite plugin.
+   */
+  get browserRuntimeManifest() {
+    return createBrowserRuntimeManifest();
+  }
+  /**
+   * Creates the integration with static declaration-only configuration.
+   *
+   * @remarks
+   * Constructors are expected to stay side-effect free. Build-manifest
+   * contributions belong in `prepareBuildContributions()` and runtime-only setup
+   * belongs in `setup()`.
+   */
   constructor(config) {
     this.name = config.name;
     this.extensions = config.extensions;
     this.integrationDependencies = config.integrationDependencies || [];
     this.staticBuildStep = config.staticBuildStep || "render";
+    this.runtimeCapability = config.runtimeCapability;
+    this.jsxImportSource = config.jsxImportSource;
   }
+  /**
+   * Attaches the finalized app config to the integration.
+   *
+   * Core calls this during config finalization before runtime setup so the
+   * integration can resolve asset paths and other app-owned services later.
+   */
   setConfig(appConfig) {
     this.appConfig = appConfig;
     this.initializeAssetDefinitionService();
   }
+  /**
+   * Records the runtime origin used for page-module loading and renderer setup.
+   */
   setRuntimeOrigin(runtimeOrigin) {
     this.runtimeOrigin = runtimeOrigin;
   }
+  /**
+   * Attaches the shared HMR manager and registers integration-owned development hooks.
+   *
+   * @remarks
+   * The default implementation registers the optional integration HMR strategy.
+   * Integrations should override this only when they need to extend that shared
+   * behavior rather than replace it.
+   */
   setHmrManager(hmrManager) {
     this.hmrManager = hmrManager;
     const strategy = this.getHmrStrategy?.();
@@ -39,6 +98,9 @@ class IntegrationPlugin {
       this.assetProcessingService.setHmrManager(hmrManager);
     }
   }
+  /**
+   * Creates the asset-processing service used for global integration dependencies.
+   */
   initializeAssetDefinitionService() {
     if (!this.appConfig) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
     this.assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
@@ -46,10 +108,16 @@ class IntegrationPlugin {
       this.assetProcessingService.setHmrManager(this.hmrManager);
     }
   }
+  /**
+   * Returns processed global assets resolved during `setup()`.
+   */
   getResolvedIntegrationDependencies() {
     return this.resolvedIntegrationDependencies;
   }
-  initializeRenderer() {
+  /**
+   * Creates the shared renderer options owned by core lifecycle setup.
+   */
+  createRendererOptions(options) {
     if (!this.appConfig) {
       throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
     }
@@ -57,31 +125,54 @@ class IntegrationPlugin {
     if (this.hmrManager) {
       assetProcessingService.setHmrManager(this.hmrManager);
     }
-    const renderer = new this.renderer({
+    return {
       appConfig: this.appConfig,
       assetProcessingService,
       resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
+      rendererModules: options?.rendererModules,
       runtimeOrigin: this.runtimeOrigin
-    });
+    };
+  }
+  /**
+   * Attaches runtime-only services after a renderer instance has been created.
+   */
+  attachRendererRuntimeServices(renderer) {
+    if (typeof renderer.name !== "string" || renderer.name.length === 0) {
+      renderer.name = this.name;
+    }
     if (this.hmrManager) {
       renderer.setHmrManager(this.hmrManager);
     }
     return renderer;
   }
   /**
-   * Declares whether a component boundary targeting this integration should be
-   * deferred through the marker pipeline.
+   * Instantiates the integration renderer with app-owned services.
    *
-   * The default implementation never defers. Integrations that require deferred
-   * subtree rendering should override this method and return `true` when their
-   * boundary must be resolved during the marker graph stage.
+   * @remarks
+   * Renderers are cheap runtime objects. They receive the finalized app config,
+   * a fresh asset-processing service, integration-global processed assets, and
+   * any renderer module context supplied by the active runtime.
+  		renderer.name ||= this.name;
+   */
+  initializeRenderer(options) {
+    const renderer = new this.renderer(this.createRendererOptions(options));
+    renderer.name ||= this.name;
+    return this.attachRendererRuntimeServices(renderer);
+  }
+  /**
+   * Prepares build-facing contributions before the app build manifest is sealed.
    *
-   * @param input Boundary metadata for the current render pass.
-   * @returns `true` when the boundary should be deferred; otherwise `false`.
+   * @remarks
+   * Integrations can override this when runtime or build plugin declarations must
+   * be materialized ahead of runtime startup. Runtime-only side effects stay in
+   * `setup()`.
    */
-  shouldDeferComponentBoundary(_input) {
-    return false;
+  async prepareBuildContributions() {
   }
+  /**
+   * Performs runtime-only integration setup after config build has already
+   * sealed manifest contributions.
+   */
   async setup() {
     if (this.integrationDependencies.length === 0) return;
     if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);
@@ -91,10 +182,20 @@ class IntegrationPlugin {
     );
     this.initializeRenderer();
   }
+  /**
+   * Releases runtime resources owned by the integration.
+   *
+   * @remarks
+   * Most integrations do not need custom teardown. Override this only for
+   * explicit cleanup such as watchers, compiler handles, or runtime registries
+   * that outlive individual requests.
+   */
   async teardown() {
   }
 }
 export {
   INTEGRATION_PLUGIN_ERRORS,
-  IntegrationPlugin
+  IntegrationPlugin,
+  assertIntegrationInvariant,
+  mergeIntegrationOptions
 };

package/src/plugins/processor.d.ts

@@ -1,9 +1,13 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
-import type { AssetDefinition } from '../services/asset-processing-service';
+import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.js';
+import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.js';
+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 declare const PROCESSOR_ERRORS: {
     readonly CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context";
 };
+export declare function mergeProcessorOptions<TDefaults, TOverrides>(defaults: TDefaults, overrides: TOverrides): TDefaults & TOverrides;
 export interface ProcessorWatchContext {
     path: string;
     bridge: IClientBridge;
@@ -38,6 +42,7 @@ export interface ProcessorConfig<TOptions = Record<string, unknown>> {
     options?: TOptions;
     watch?: ProcessorWatchConfig;
     capabilities?: ProcessorAssetCapability[];
+    runtimeCapability?: RuntimeCapabilityDeclaration;
 }
 export interface ProcessorContext {
     config: EcoPagesAppConfig;
@@ -59,12 +64,22 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
     protected options?: TOptions;
     protected watchConfig?: ProcessorWatchConfig;
     protected capabilities: ProcessorAssetCapability[];
+    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
     /** Plugins that are only used during the build process */
     abstract buildPlugins?: EcoBuildPlugin[];
     /** Plugins that are used during runtime for file processing */
     abstract plugins?: EcoBuildPlugin[];
     constructor(config: ProcessorConfig<TOptions>);
     setContext(appConfig: EcoPagesAppConfig): void;
+    /**
+     * Prepares build-facing processor contributions before config finalization.
+     *
+     * @remarks
+     * Override this when a processor must compute runtime/build plugins or other
+     * manifest-owned state before startup. Runtime-only work such as cache
+     * warming or watcher registration should stay in `setup()`.
+     */
+    prepareBuildContributions(): Promise<void>;
     abstract setup(): Promise<void>;
     abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;

package/src/plugins/processor.js

@@ -1,9 +1,14 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { GENERATED_BASE_PATHS } from "../constants";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
+import { GENERATED_BASE_PATHS } from "../config/constants.js";
+import { deepMerge } from "../utils/deep-merge.js";
 const PROCESSOR_ERRORS = {
   CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context"
 };
+function mergeProcessorOptions(defaults, overrides) {
+  return deepMerge(defaults, overrides);
+}
 function resolveGeneratedPath(type, options) {
   const { root, module, subPath } = options;
   const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
@@ -16,15 +21,18 @@ class Processor {
   options;
   watchConfig;
   capabilities = [];
+  runtimeCapability;
   constructor(config) {
     this.name = config.name;
     this.options = config.options;
     this.watchConfig = config.watch;
     this.capabilities = config.capabilities ?? [];
+    this.runtimeCapability = config.runtimeCapability;
   }
   setContext(appConfig) {
+    const workDir = appConfig.absolutePaths.workDir ?? path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
     const cachePath = resolveGeneratedPath("cache", {
-      root: appConfig.absolutePaths.distDir,
+      root: workDir,
       module: this.name
     });
     fileSystem.ensureDir(cachePath);
@@ -36,6 +44,16 @@ class Processor {
       cache: cachePath
     };
   }
+  /**
+   * Prepares build-facing processor contributions before config finalization.
+   *
+   * @remarks
+   * Override this when a processor must compute runtime/build plugins or other
+   * manifest-owned state before startup. Runtime-only work such as cache
+   * warming or watcher registration should stay in `setup()`.
+   */
+  async prepareBuildContributions() {
+  }
   getCachePath(key) {
     return `${this.context?.cache}/${key}`;
   }
@@ -118,5 +136,6 @@ class Processor {
 }
 export {
   PROCESSOR_ERRORS,
-  Processor
+  Processor,
+  mergeProcessorOptions
 };

package/src/plugins/runtime-capability.d.ts

@@ -0,0 +1,9 @@
+export type RuntimeCapabilityTag = 'bun-only' | 'node-compatible' | 'requires-native-bun-api' | 'requires-node-builtins';
+/**
+ * Declares the runtime assumptions a plugin makes so config finalization can
+ * reject incompatible startup environments before bootstrapping the app.
+ */
+export interface RuntimeCapabilityDeclaration {
+    tags: RuntimeCapabilityTag[];
+    minRuntimeVersion?: string;
+}

package/src/plugins/source-transform.d.ts

@@ -0,0 +1,46 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export interface EcoSourceTransformResult {
+    code: string;
+    map?: unknown;
+}
+export interface EcoSourceTransform {
+    name: string;
+    filter: RegExp;
+    enforce?: 'pre' | 'post';
+    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
+}
+export interface EcoViteCompatiblePlugin {
+    name: string;
+    enforce?: 'pre' | 'post';
+    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
+}
+/**
+ * Normalizes bundler module ids so one transform can serve Ecopages loaders,
+ * Vite, and future bundler adapters.
+ */
+export declare function normalizeTransformId(id: string): string;
+/**
+ * Applies one source transform if the normalized id matches its filter.
+ */
+export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * Adapts a source transform into the existing Ecopages build-plugin contract.
+ */
+export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
+/**
+ * Adapts a source transform into a Vite-compatible plugin object.
+ *
+ * @remarks
+ * This intentionally returns a plain object shape so core does not need a hard
+ * dependency on `vite` just to author transform primitives.
+ */
+export declare function createVitePluginFromSourceTransform(transform: EcoSourceTransform): EcoViteCompatiblePlugin;
+/**
+ * Returns the app-owned source transforms in stable registration order.
+ */
+export declare function getAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoSourceTransform[];
+/**
+ * Adapts the app-owned source transforms into Vite-compatible plugin objects.
+ */
+export declare function createVitePluginsFromAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoViteCompatiblePlugin[];