@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.20

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

@@ -9,274 +9,17 @@
  *   {@link ViteHostBuildAdapter} (a host-owned boundary marker that throws
  *   on direct use, for host runtimes that own their own build pipeline).
  * - `BuildExecutor` — the runtime-facing facade stored on
- *   `appConfig.runtime.buildExecutor`. It is intentionally narrower than
- *   `BuildAdapter` so callers that only need to issue builds do not depend
- *   on `resolve` / `getTranspileOptions`.
- * - App-owned helpers (`getAppBuildAdapter`, `getAppBuildExecutor`, and
- *   the `set*` counterparts) — the supported way for runtime code to read
- *   and mutate the active adapter per `EcoPagesAppConfig`.
+ *   `appConfig.runtime.buildRuntime` via profile-based accessors.
+ * - App-owned helpers (`getAppBuildAdapter` and the `set*` counterparts) —
+ *   the supported way for runtime code to read and mutate the active adapter
+ *   per `EcoPagesAppConfig`. Profile executors live on
+ *   `appConfig.runtime.buildRuntime`.
  */
 import type { EcoBuildPlugin } from './build-types.js';
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildOwnership, type BuildResult, type BuildTranspileOptions, type BuildTranspileProfile } from './build-contracts.js';
+export type { BuildAdapter, BuildDependencyGraph, BuildExecutor, BuildLog, BuildOptions, BuildOutput, BuildOwnership, BuildResult, BuildTranspileOptions, BuildTranspileProfile, } from './build-contracts.js';
 import { type AppBuildManifest } from './build-manifest.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { IHmrManager } from '../types/public-types.js';
-/**
- * Which backend owns the app's build pipeline.
- *
- * - `'rolldown'`: the default. Ecopages runs the build directly through
- *   its bundler-backed adapter.
- * - `'rolldown-dev'`: uses Rolldown's DevEngine for cached incremental
- *   rebuilds. Ideal for HMR and watch mode where the same entrypoints
- *   are rebuilt repeatedly.
- * - `'vite-host'`: a host runtime owns the build. {@link ViteHostBuildAdapter}
- *   is exposed as a boundary marker; any direct call into it throws.
- */
-export type BuildOwnership = 'vite-host' | 'rolldown' | 'rolldown-dev';
-/**
- * A single message emitted by the build backend.
- *
- * @remarks
- * Today this only carries `message`. Severity and structured fields
- * belong in a future schema bump; the current shape mirrors the
- * bundler's log output 1:1.
- */
-export interface BuildLog {
-    message: string;
-}
-/**
- * A single artifact emitted by the build backend.
- *
- * @remarks
- * `path` is the absolute on-disk path of the emitted file. For
- * filename templates that include a content-hash token, the bundler
- * returns the concrete resolved path (not the template), so callers
- * can read the file directly.
- */
-export interface BuildOutput {
-    path: string;
-}
-/**
- * Per-entrypoint dependency metadata surfaced alongside a build.
- *
- * @remarks
- * Populated from the bundler's per-chunk module list and exposed as a
- * normalized absolute-path map. Consumers (HMR invalidation, the build
- * manifest) read this without needing to know which adapter produced
- * it. The shape is preserved across adapters so historical callers
- * continue to compile.
- */
-export interface BuildDependencyGraph {
-    /**
-     * Normalized absolute entrypoint path mapped to every normalized
-     * absolute source input that contributed to that entrypoint's
-     * output, including the entrypoint itself.
-     */
-    entrypoints: Record<string, string[]>;
-}
-/**
- * The full result of one `BuildAdapter.build` call.
- *
- * @remarks
- * `success === false` means the build failed and `outputs` will be
- * empty. Inspect `logs` for the error message; the original `Error` is
- * already normalized into `BuildLog` shape.
- */
-export interface BuildResult {
-    success: boolean;
-    logs: BuildLog[];
-    outputs: BuildOutput[];
-    /**
-     * Per-entrypoint dependency metadata, when the backend produced it.
-     * Some backends (notably the Vite-host boundary marker) leave this
-     * undefined; callers must treat that as a valid state and fall
-     * back deterministically.
-     */
-    dependencyGraph?: BuildDependencyGraph;
-}
-/**
- * Options accepted by every `BuildAdapter.build` call.
- *
- * @remarks
- * Fields that the adapter can forward are honored; fields that cannot
- * (currently `splitting`, `bundle`, and `outbase`) are accepted so
- * call-sites compile, but the adapter ignores them. See each field's
- * docstring for the current behavior.
- */
-export interface BuildOptions {
-    /**
-     * Absolute or context-root-relative source files that begin the build graph.
-     *
-     * Use a record (key → source path) when the caller needs to control chunk
-     * names. Keys become the `[name]` token in `naming`, which lets the caller
-     * embed path information that the bundler would otherwise strip.
-     */
-    entrypoints: string[] | Record<string, string>;
-    /** Output directory. Defaults to `dist/assets` when omitted. */
-    outdir?: string;
-    /**
-     * Base directory for `[dir]` placeholders in `naming`. Currently
-     * the bundled adapter derives the base from `root` directly and
-     * ignores this field.
-     */
-    outbase?: string;
-    /**
-     * Filename pattern for entrypoints. The bundled adapter honors
-     * `[name]`, `[hash]`, and `[ext]`. The `[dir]` token is stripped
-     * before forwarding to the bundler (rolldown does not implement it);
-     * callers that need directory structure preserved should use the
-     * record form of `entrypoints` so each key becomes its own chunk.
-     * When omitted, the bundler's default applies.
-     */
-    naming?: string;
-    /**
-     * Package export conditions to honor during resolution
-     * (e.g. `['import', 'browser', 'default']`).
-     */
-    conditions?: string[];
-    /**
-     * Global identifier replacements. Honored by the bundled adapter.
-     */
-    define?: Record<string, string>;
-    /** Run the bundler's minifier. Off by default. */
-    minify?: boolean;
-    /** Enable the bundler's tree-shaker. Defaults to `true`. */
-    treeshaking?: boolean;
-    /**
-     * Output target family. Accepted values: `'browser'`, `'node'`,
-     * anything else falls through to a platform-neutral setup.
-     */
-    target?: string;
-    /** Output module format. Accepted: `'esm'`, `'cjs'`, `'iife'`. */
-    format?: string;
-    /**
-     * Source map mode. Accepted: `'none'`, `'inline'`, `'external'`,
-     * `'linked'`. Anything else maps to the bundler's default (linked).
-     */
-    sourcemap?: string;
-    /**
-     * Historical code-splitting flag. Currently a no-op on the bundled
-     * adapter: the bundler splits by default and this flag is not
-     * forwarded. See the per-chunk naming convention in the adapter for
-     * the available control.
-     */
-    splitting?: boolean;
-    /** Project root used to resolve relative paths and the tsconfig lookup. */
-    root?: string;
-    /**
-     * Historical bundle flag. Currently a no-op on the bundled adapter:
-     * the bundler always bundles. Accepted so call-sites compile.
-     */
-    bundle?: boolean;
-    /**
-     * Treat `node_modules` packages as external. Honored by the bundled
-     * adapter.
-     */
-    externalPackages?: boolean;
-    /** Explicit list of module specifiers to leave as external imports. */
-    external?: string[];
-    /**
-     * JSX runtime configuration. Mirrors the bundler's `jsx` option shape.
-     */
-    jsx?: {
-        development?: boolean;
-        factory?: string;
-        fragment?: string;
-        importSource?: string;
-        runtime?: 'classic' | 'automatic';
-        sideEffects?: boolean;
-    };
-    /**
-     * Runtime-agnostic `EcoBuildPlugin[]` to attach to this build. The
-     * bundled adapter translates the array via the rolldown plugin
-     * bridge.
-     */
-    plugins?: EcoBuildPlugin[];
-    /**
-     * Escape hatch for backends that need to forward unknown options
-     * to their underlying driver. Consumers should prefer the typed
-     * fields above.
-     */
-    [key: string]: unknown;
-}
-/** Stable profile identifiers for `BuildAdapter.getTranspileOptions`. */
-export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
-/**
- * Resolved transpile settings for a given profile.
- *
- * @remarks
- * The three fields map 1:1 to the trio the HMR and browser-script
- * code paths look at: target platform, output format, and source-map
- * mode. Today the bundled adapter returns identical defaults for all
- * three profiles; the type is kept open so per-profile tuning can
- * land without breaking callers.
- */
-export interface BuildTranspileOptions {
-    target: string;
-    format: string;
-    sourcemap: string;
-}
-/**
- * Low-level build backend contract.
- *
- * @remarks
- * One instance is owned by each `EcoPagesAppConfig` (see
- * {@link getAppBuildAdapter}). Two implementations exist: the bundled
- * adapter does the work; {@link ViteHostBuildAdapter} is a host-owned
- * boundary marker that throws on direct use.
- */
-export interface BuildAdapter {
-    /** Which backend owns this adapter. Used for routing decisions in app helpers. */
-    readonly ownership?: BuildOwnership;
-    /**
-     * Run one build.
-     *
-     * @remarks
-     * Implementations are expected to be safe to call from any caller.
-     * Concurrent calls are not guaranteed to be serialized by the
-     * adapter itself; the dev-watch pipeline wraps the adapter in
-     * {@link SerializedBuildExecutor} when it needs FIFO ordering.
-     *
-     * Returns a `BuildResult` with `success: false` on failure; the
-     * thrown-error variant (`buildOrThrow`) is reserved for callers
-     * that need the original `Error` object.
-     */
-    build(options: BuildOptions): Promise<BuildResult>;
-    /**
-     * Resolve a module specifier against the project's `rootDir`.
-     *
-     * @remarks
-     * Used by the source-loading services when they need to know the
-     * absolute path of a specifier without performing a full build.
-     */
-    resolve(importPath: string, rootDir: string): string;
-    /**
-     * Resolve transpile settings for a known profile.
-     *
-     * @remarks
-     * Today the bundled adapter returns identical defaults for all
-     * profiles. The profile argument is kept so per-profile tuning
-     * can land without breaking callers.
-     */
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}
-/**
- * Runtime-facing facade for issuing builds.
- *
- * @remarks
- * Strictly narrower than {@link BuildAdapter}: it only exposes `build`.
- * This is the shape stored on `appConfig.runtime.buildExecutor` and
- * passed across the dev-watch and server-module-loading seams, so
- * callers cannot accidentally depend on `resolve` or
- * `getTranspileOptions`.
- *
- * In production and non-watch flows the executor is the adapter
- * itself. In development watch flows the executor is a
- * {@link SerializedBuildExecutor} wrapping the adapter so dev-watch
- * pipelines are FIFO-serialized.
- */
-export interface BuildExecutor {
-    build(options: BuildOptions): Promise<BuildResult>;
-}
 /**
  * Wraps a {@link BuildExecutor} so each call to `build` receives the
  * union of the caller's `options.plugins` and the plugins sourced
@@ -287,9 +30,9 @@ export interface BuildExecutor {
  * `ConfigBuilder` stores a raw adapter on
  * `appConfig.runtime.buildAdapter` and the
  * `installAppRuntimeBuildExecutor` step wraps that adapter with this
- * helper. Callers that issue builds against
- * `appConfig.runtime.buildExecutor` get the merged plugin set without
- * further ceremony.
+ * helper. Callers that issue builds through
+ * `requireBuildRuntime(appConfig).getProfile(...)` get the merged plugin set
+ * without further ceremony.
  */
 export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
 /**
@@ -415,43 +158,7 @@ export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppC
  * caller-supplied contribution input.
  */
 export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
-/**
- * Collects the build-facing processor and integration contributions
- * that should be sealed into the app manifest during config
- * finalization.
- *
- * @remarks
- * Runs `prepareBuildContributions()` on every processor and
- * integration. Runtime-only side effects (HMR registration, cache
- * prewarming, runtime-origin wiring) belong to the startup path and
- * must not be triggered here; use {@link setupAppRuntimePlugins} for
- * those.
- *
- * @returns The new manifest's runtime / browser / browser-runtime-manifest
- * contribution buckets. Caller seals them into a manifest via
- * {@link updateAppBuildManifest}.
- */
-export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
-/**
- * Runs runtime-only processor and integration setup against an already
- * sealed app manifest.
- *
- * @remarks
- * Startup paths call this after `ConfigBuilder.build` has finalized
- * the manifest. The manifest is reused as-is; this helper only performs
- * the runtime side effects that need live startup context (cache
- * prewarming, runtime-origin wiring, HMR manager attachment).
- *
- * Loaders, processors, and integrations are visited in that order;
- * each one's plugins are forwarded to the optional `onRuntimePlugin`
- * callback so callers can attach to every plugin discovered.
- */
-export declare function setupAppRuntimePlugins(options: {
-    appConfig: EcoPagesAppConfig;
-    runtimeOrigin: string;
-    hmrManager?: IHmrManager;
-    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
-}): Promise<void>;
+export { collectConfiguredAppBuildManifestContributions, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
 /**
  * Returns the server-bundle plugin list for one app/runtime instance.
  *
@@ -468,28 +175,19 @@ export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig):
  * Reads from the app's sealed build manifest. The browser-bundle
  * manifest is the source of truth for which plugins participate in the
  * browser bundle.
- */
-export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
-/**
- * Returns the executor owned by an app/runtime instance.
  *
- * @remarks
- * Falls back to {@link getAppBuildAdapter} when no executor is set
- * on the runtime yet. The dev-watch pipeline replaces this value with
- * a {@link SerializedBuildExecutor} via
- * {@link installAppRuntimeBuildExecutor}.
+ * Plugins whose `name` matches a registered {@link EcoSourceTransform} are
+ * excluded here because browser builds run those transforms via the Rolldown
+ * bridge post-load pass instead of as competing `onLoad` handlers.
  */
-export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
-/** Installs the executor that should serve future builds for one app instance. */
-export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
 /**
  * Runs a build through the active pipeline.
  *
  * @remarks
  * `executor` defaults to the default-bundler adapter for non-app-aware
- * callsites. App-aware code should pass
- * `getAppBuildExecutor(appConfig)` (or read it directly) to honor the
- * per-app pipeline.
+ * callsites. App-aware code should pass a profile executor from
+ * {@link requireBuildRuntime} to honor the per-app pipeline.
  */
 export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
 /**

package/src/build/build-adapter.js

@@ -1,13 +1,15 @@
-import { mergeBrowserRuntimeManifests } from "./browser-runtime-manifest.js";
 import { normalizeNodeRuntimeBuildOutputs } from "./runtime-build-output-normalizer.js";
-import { createForeignJsxOverridePlugin } from "../plugins/foreign-jsx-override-plugin.js";
+import {
+} from "./build-contracts.js";
 import {
   createAppBuildManifest,
   getBrowserBuildPlugins,
   getServerBuildPlugins
 } from "./build-manifest.js";
+import { getAppSourceTransforms } from "../plugins/source-transform.js";
+import { createAliasResolverPlugin } from "../plugins/alias-resolver-plugin.js";
+import { getJsxOwnershipPlugins } from "./jsx-ownership-plugins.js";
 import { createRolldownBuildAdapter } from "./rolldown-build-adapter.js";
-import { createRolldownDevBuildAdapter } from "./rolldown-dev-build-adapter.js";
 function mergeBuildExecutorPlugins(existing, appPlugins) {
   if (!existing || existing.length === 0) {
     return appPlugins;
@@ -35,6 +37,12 @@ function withBuildExecutorPlugins(executor, getPlugins) {
     }
   };
 }
+function patchAppRuntime(appConfig, patch) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    ...patch
+  };
+}
 function createHostOwnedBuildError(methodName) {
   return new Error(
     `Vite-hosted builds are owned by the host runtime. Core cannot ${methodName} through the host-owned compatibility adapter.`
@@ -59,8 +67,6 @@ function createBuildAdapter(options) {
   switch (options?.ownership ?? "rolldown") {
     case "vite-host":
       return createViteHostBuildAdapter();
-    case "rolldown-dev":
-      return createRolldownDevBuildAdapter();
     case "rolldown":
     default:
       return createRolldownBuildAdapter();
@@ -79,31 +85,24 @@ function getAppBuildOwnership(appConfig) {
   return appConfig.runtime?.buildOwnership ?? getBuildAdapterOwnership(appConfig.runtime?.buildAdapter);
 }
 function setAppBuildOwnership(appConfig, buildOwnership) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildOwnership
-  };
+  patchAppRuntime(appConfig, { buildOwnership });
 }
 function getAppBuildAdapter(appConfig) {
   return appConfig.runtime?.buildAdapter ?? getDefaultBuildAdapter(getAppBuildOwnership(appConfig));
 }
 function setAppBuildAdapter(appConfig, buildAdapter) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
+  patchAppRuntime(appConfig, {
     buildOwnership: getBuildAdapterOwnership(buildAdapter),
     buildAdapter
-  };
+  });
 }
 function getAppBuildManifest(appConfig) {
   return appConfig.runtime?.buildManifest ?? createAppBuildManifest({
-    loaderPlugins: Array.from(appConfig.loaders.values())
+    loaderPlugins: Array.from(appConfig.loaders?.values() ?? [])
   });
 }
 function setAppBuildManifest(appConfig, buildManifest) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildManifest
-  };
+  patchAppRuntime(appConfig, { buildManifest });
 }
 function createConfiguredAppBuildManifest(appConfig, input) {
   return createAppBuildManifest({
@@ -116,85 +115,22 @@ function createConfiguredAppBuildManifest(appConfig, input) {
 function updateAppBuildManifest(appConfig, input) {
   setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
 }
-async function collectConfiguredAppBuildManifestContributions(appConfig) {
-  const runtimePlugins = [];
-  const browserBundlePlugins = [];
-  const browserRuntimeManifests = [];
-  for (const processor of appConfig.processors.values()) {
-    await processor.prepareBuildContributions();
-    if (processor.plugins) {
-      runtimePlugins.push(...processor.plugins);
-    }
-    if (processor.buildPlugins) {
-      browserBundlePlugins.push(...processor.buildPlugins);
-    }
-  }
-  for (const integration of appConfig.integrations) {
-    integration.setConfig(appConfig);
-    await integration.prepareBuildContributions();
-    runtimePlugins.push(...integration.plugins ?? []);
-    browserBundlePlugins.push(...integration.browserBuildPlugins ?? []);
-    browserRuntimeManifests.push(integration.browserRuntimeManifest);
-  }
-  return {
-    runtimePlugins,
-    browserBundlePlugins,
-    browserRuntimeManifest: mergeBrowserRuntimeManifests(...browserRuntimeManifests)
-  };
-}
-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) {
-      for (const plugin of processor.plugins) {
-        options.onRuntimePlugin?.(plugin);
-      }
-    }
-  }
-  for (const integration of options.appConfig.integrations) {
-    integration.setConfig(options.appConfig);
-    integration.setRuntimeOrigin(options.runtimeOrigin);
-    if (options.hmrManager) {
-      integration.setHmrManager(options.hmrManager);
-    }
-    await integration.setup();
-    for (const plugin of integration.plugins) {
-      options.onRuntimePlugin?.(plugin);
-    }
-  }
-}
+import {
+  collectConfiguredAppBuildManifestContributions,
+  setupAppRuntimePlugins
+} from "./app-build-manifest-runtime.js";
 function getAppServerBuildPlugins(appConfig) {
-  return getServerBuildPlugins(getAppBuildManifest(appConfig));
+  const srcDir = appConfig.absolutePaths?.srcDir;
+  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
 }
 function getAppBrowserBuildPlugins(appConfig) {
   const manifest = getAppBuildManifest(appConfig);
-  const jsxOwnershipPlugins = collectJsxOwnershipPlugins(appConfig);
-  return [...getBrowserBuildPlugins(manifest), ...jsxOwnershipPlugins];
-}
-function collectJsxOwnershipPlugins(appConfig) {
-  const jsxExtensions = (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
-    (integration) => integration.extensions.filter((extension) => extension.endsWith(".tsx") || extension.endsWith(".jsx")).map((extension) => ({ integration, extension }))
-  ).sort((left, right) => right.extension.length - left.extension.length);
-  return jsxExtensions.map(
-    ({ integration, extension }) => createForeignJsxOverridePlugin({
-      hostJsxImportSource: integration.jsxImportSource,
-      foreignExtensions: [extension],
-      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
-      name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
-    })
-  );
-}
-function getAppBuildExecutor(appConfig) {
-  return appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
-}
-function setAppBuildExecutor(appConfig, buildExecutor) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildExecutor
-  };
+  const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
+  const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
+  const srcDir = appConfig.absolutePaths?.srcDir;
+  const aliasPlugin = srcDir ? [createAliasResolverPlugin(srcDir)] : [];
+  return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
 function build(options, executor = defaultRolldownBuildAdapter) {
   return executor.build(options).then((result) => {
@@ -225,7 +161,6 @@ export {
   defaultViteHostBuildAdapter,
   getAppBrowserBuildPlugins,
   getAppBuildAdapter,
-  getAppBuildExecutor,
   getAppBuildManifest,
   getAppBuildOwnership,
   getAppServerBuildPlugins,
@@ -234,7 +169,6 @@ export {
   getDefaultBuildAdapter,
   getTranspileOptions,
   setAppBuildAdapter,
-  setAppBuildExecutor,
   setAppBuildManifest,
   setAppBuildOwnership,
   setupAppRuntimePlugins,

package/src/build/build-contracts.d.ts

@@ -0,0 +1,97 @@
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { EcoBuildPlugin } from './build-types.js';
+/**
+ * Which backend owns the app's build pipeline.
+ *
+ * - `'rolldown'`: the default. Ecopages runs the build directly through
+ *   its bundler-backed adapter.
+ * - `'vite-host'`: a host runtime owns the build. {@link ViteHostBuildAdapter}
+ *   is exposed as a boundary marker; any direct call into it throws.
+ */
+export type BuildOwnership = 'vite-host' | 'rolldown';
+/** A single message emitted by the build backend. */
+export interface BuildLog {
+    message: string;
+}
+/** A single artifact emitted by the build backend. */
+export interface BuildOutput {
+    path: string;
+}
+/** Per-entrypoint dependency metadata surfaced alongside a build. */
+export interface BuildDependencyGraph {
+    entrypoints: Record<string, string[]>;
+}
+/** The full result of one `BuildAdapter.build` call. */
+export interface BuildResult {
+    success: boolean;
+    logs: BuildLog[];
+    outputs: BuildOutput[];
+    dependencyGraph?: BuildDependencyGraph;
+    entryOutputs?: Record<string, string>;
+}
+/**
+ * Options accepted by every `BuildAdapter.build` call.
+ *
+ * @remarks
+ * Fields that the adapter can forward are honored; fields that cannot
+ * (currently `splitting`, `bundle`, and `outbase`) are accepted so
+ * call-sites compile, but the adapter ignores them.
+ */
+export interface BuildOptions {
+    entrypoints: string[] | Record<string, string>;
+    outdir?: string;
+    /**
+     * Base directory for `[dir]` placeholders in `naming`. Currently
+     * the bundled adapter derives the base from `root` directly and
+     * ignores this field.
+     *
+     * @deprecated Accepted for call-site compatibility only. Use record-form
+     * `entrypoints` keys to preserve directory structure.
+     */
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    target?: string;
+    format?: string;
+    sourcemap?: string;
+    /** @deprecated Accepted for call-site compatibility only. */
+    splitting?: boolean;
+    root?: string;
+    /** @deprecated Accepted for call-site compatibility only. */
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
+    plugins?: EcoBuildPlugin[];
+    sourceTransforms?: EcoSourceTransform[];
+    [key: string]: unknown;
+}
+/** Stable profile identifiers for `BuildAdapter.getTranspileOptions`. */
+export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+/** Resolved transpile settings for a given profile. */
+export interface BuildTranspileOptions {
+    target: string;
+    format: string;
+    sourcemap: string;
+}
+/** Low-level build backend contract. */
+export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+/** Runtime-facing facade for issuing builds. */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}