@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/build/build-adapter.js

@@ -1,281 +1,279 @@
-import { mergeBrowserRuntimeManifests } from "./browser-runtime-manifest.js";
-import { normalizeNodeRuntimeBuildOutputs } from "./runtime-build-output-normalizer.js";
-import {
-  createAppBuildManifest,
-  getBrowserBuildPlugins,
-  getServerBuildPlugins
-} from "./build-manifest.js";
-import { getJsxOwnershipPlugins } from "./jsx-ownership-plugins.js";
-import { createRolldownBuildAdapter } from "./rolldown-build-adapter.js";
-import { createRolldownDevBuildAdapter } from "./rolldown-dev-build-adapter.js";
-import { appLogger } from "../global/app-logger.js";
-function mergeBuildExecutorPlugins(existing, appPlugins) {
-  if (!existing || existing.length === 0) {
-    return appPlugins;
-  }
-  const byName = /* @__PURE__ */ new Map();
-  for (const plugin of existing) {
-    byName.set(plugin.name, plugin);
-  }
-  for (const plugin of appPlugins) {
-    byName.set(plugin.name, plugin);
-  }
-  return Array.from(byName.values());
-}
-function withBuildExecutorPlugins(executor, getPlugins) {
-  return {
-    async build(options) {
-      const appPlugins = getPlugins();
-      if (appPlugins.length === 0) {
-        return executor.build(options);
-      }
-      return executor.build({
-        ...options,
-        plugins: mergeBuildExecutorPlugins(options.plugins, appPlugins)
-      });
-    }
-  };
+/**
+ * Build pipeline contracts and app-owned adapter wiring.
+ *
+ * @remarks
+ * The build layer exposes three concentric shapes:
+ *
+ * - `BuildAdapter` — the low-level backend contract. Two implementations
+ *   exist: a bundler-backed adapter (the real backend) and
+ *   {@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.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 {} from './contracts/build-contracts.js';
+import { createAppBuildManifest, getBrowserBuildPlugins, getServerBuildPlugins, } from './contracts/build-manifest.js';
+import { getAppSourceTransforms } from '../plugins/source-transform.js';
+import { createAliasResolverPlugin } from '../plugins/alias-resolver-plugin.js';
+import { getJsxOwnershipPlugins } from './browser/jsx-ownership-plugins.js';
+import { createRolldownBuildAdapter } from './rolldown/rolldown-build-adapter.js';
+/**
+ * @remarks
+ * All runtime-bag setters funnel through here so `appConfig.runtime` is patched
+ * in one place instead of repeating the spread-merge at every call site.
+ */
+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.`
-  );
-}
-class ViteHostBuildAdapter {
-  ownership = "vite-host";
-  async build(_options) {
-    throw createHostOwnedBuildError("build");
-  }
-  resolve(_importPath, _rootDir) {
-    throw createHostOwnedBuildError("resolve imports");
-  }
-  getTranspileOptions(_profile) {
-    throw createHostOwnedBuildError("derive transpile options");
-  }
-}
-function createViteHostBuildAdapter() {
-  return new ViteHostBuildAdapter();
-}
-function createBuildAdapter(options) {
-  switch (options?.ownership ?? "rolldown") {
-    case "vite-host":
-      return createViteHostBuildAdapter();
-    case "rolldown-dev":
-      return createRolldownDevBuildAdapter();
-    case "rolldown":
-    default:
-      return createRolldownBuildAdapter();
-  }
-}
-const defaultRolldownBuildAdapter = createBuildAdapter({ ownership: "rolldown" });
-const defaultViteHostBuildAdapter = createBuildAdapter({ ownership: "vite-host" });
-const defaultBuildAdapter = defaultRolldownBuildAdapter;
-function getDefaultBuildAdapter(ownership = "rolldown") {
-  return ownership === "vite-host" ? defaultViteHostBuildAdapter : defaultRolldownBuildAdapter;
+    return new Error(`Vite-hosted builds are owned by the host runtime. Core cannot ${methodName} through the host-owned compatibility adapter.`);
 }
-function getBuildAdapterOwnership(buildAdapter) {
-  return buildAdapter?.ownership ?? "rolldown";
-}
-function getAppBuildOwnership(appConfig) {
-  return appConfig.runtime?.buildOwnership ?? getBuildAdapterOwnership(appConfig.runtime?.buildAdapter);
-}
-function setAppBuildOwnership(appConfig, buildOwnership) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildOwnership
-  };
-}
-function getAppBuildAdapter(appConfig) {
-  return appConfig.runtime?.buildAdapter ?? getDefaultBuildAdapter(getAppBuildOwnership(appConfig));
-}
-function setAppBuildAdapter(appConfig, buildAdapter) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildOwnership: getBuildAdapterOwnership(buildAdapter),
-    buildAdapter
-  };
+/**
+ * Boundary-marker adapter for Vite-host ownership.
+ *
+ * @remarks
+ * This is not a real backend. It exists so `appConfig.runtime.buildAdapter`
+ * can carry the `'vite-host'` ownership without falling back to a
+ * framework-owned bundler path. Every method throws a
+ * {@link createHostOwnedBuildError} so misrouted calls fail loudly
+ * with a clear message instead of silently executing under a
+ * different backend.
+ *
+ * The class stays in the public surface for host runtimes that own
+ * their build pipeline (e.g. Nitro) and for app code that wants to
+ * opt into host-owned ownership before its host wires up the build.
+ */
+export class ViteHostBuildAdapter {
+    ownership = 'vite-host';
+    async build(_options) {
+        throw createHostOwnedBuildError('build');
+    }
+    resolve(_importPath, _rootDir) {
+        throw createHostOwnedBuildError('resolve imports');
+    }
+    getTranspileOptions(_profile) {
+        throw createHostOwnedBuildError('derive transpile options');
+    }
 }
-function getAppBuildManifest(appConfig) {
-  return appConfig.runtime?.buildManifest ?? createAppBuildManifest({
-    loaderPlugins: Array.from(appConfig.loaders?.values() ?? [])
-  });
+/**
+ * Constructs a {@link ViteHostBuildAdapter}. Use only in code paths
+ * that explicitly opt into the host-owned boundary.
+ */
+export function createViteHostBuildAdapter() {
+    return new ViteHostBuildAdapter();
 }
-function setAppBuildManifest(appConfig, buildManifest) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildManifest
-  };
+/**
+ * Constructs a build adapter for the given ownership.
+ *
+ * @param options - When `options.ownership` is omitted, the default is
+ * `'rolldown'`. The Vite-host path is opt-in.
+ */
+export function createBuildAdapter(options) {
+    switch (options?.ownership ?? 'rolldown') {
+        case 'vite-host':
+            return createViteHostBuildAdapter();
+        case 'rolldown':
+        default:
+            return createRolldownBuildAdapter();
+    }
 }
-function createConfiguredAppBuildManifest(appConfig, input) {
-  return createAppBuildManifest({
-    loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
-    runtimePlugins: input?.runtimePlugins,
-    browserBundlePlugins: input?.browserBundlePlugins,
-    browserRuntimeManifest: input?.browserRuntimeManifest
-  });
+/** The shared default-bundler backend instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export const defaultRolldownBuildAdapter = createBuildAdapter({ ownership: 'rolldown' });
+/** The shared Vite-host boundary instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export const defaultViteHostBuildAdapter = createBuildAdapter({ ownership: 'vite-host' });
+/**
+ * Global default build adapter.
+ *
+ * @remarks
+ * Resolves to the bundled default-bundler adapter. New app-aware
+ * code should prefer {@link getAppBuildAdapter}.
+ */
+export const defaultBuildAdapter = defaultRolldownBuildAdapter;
+/**
+ * Resolves the default build adapter for an ownership value.
+ *
+ * @param ownership - Defaults to `'rolldown'`. Returns the
+ * {@link ViteHostBuildAdapter} only when the caller explicitly asks
+ * for `'vite-host'`.
+ */
+export function getDefaultBuildAdapter(ownership = 'rolldown') {
+    return ownership === 'vite-host' ? defaultViteHostBuildAdapter : defaultRolldownBuildAdapter;
 }
-function updateAppBuildManifest(appConfig, input) {
-  setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
+/**
+ * Reads the {@link BuildOwnership} declared on a {@link BuildAdapter}.
+ *
+ * @param buildAdapter - When `undefined`, defaults to `'rolldown'`.
+ */
+export function getBuildAdapterOwnership(buildAdapter) {
+    return buildAdapter?.ownership ?? 'rolldown';
 }
-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)
-  };
+/**
+ * Resolves the build ownership of an app config.
+ *
+ * @remarks
+ * Resolution order: `appConfig.runtime.buildOwnership` (explicit), then
+ * the ownership declared on `appConfig.runtime.buildAdapter`, then the
+ * default `'rolldown'`.
+ */
+export function getAppBuildOwnership(appConfig) {
+    return appConfig.runtime?.buildOwnership ?? getBuildAdapterOwnership(appConfig.runtime?.buildAdapter);
 }
-async function setupAppRuntimePlugins(options) {
-  if (options.appConfig.runtime?.runtimeAssetsPrepared) {
-    appLogger.debug("Skipped setupAppRuntimePlugins: runtime assets already prepared");
-    for (const loader of options.appConfig.loaders.values()) {
-      options.onRuntimePlugin?.(loader);
-    }
-    for (const processor of options.appConfig.processors.values()) {
-      if (processor.plugins) {
-        for (const plugin of processor.plugins) {
-          options.onRuntimePlugin?.(plugin);
-        }
-      }
-    }
-    for (const integration of options.appConfig.integrations) {
-      for (const plugin of integration.plugins) {
-        options.onRuntimePlugin?.(plugin);
-      }
-    }
-    return;
-  }
-  appLogger.debugTime("setupAppRuntimePlugins");
-  try {
-    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);
-      }
-    }
-    options.appConfig.runtime = {
-      ...options.appConfig.runtime ?? {},
-      runtimeAssetsPrepared: true
-    };
-  } finally {
-    appLogger.debugTimeEnd("setupAppRuntimePlugins");
-  }
+/**
+ * Sets the explicit build ownership on an app config.
+ *
+ * @remarks
+ * The `ConfigBuilder` uses this when the caller calls
+ * `setBuildOwnership`. App code that needs a different ownership
+ * should call this directly with a new value; passing the same
+ * value is a no-op.
+ */
+export function setAppBuildOwnership(appConfig, buildOwnership) {
+    patchAppRuntime(appConfig, { buildOwnership });
 }
-function getAppServerBuildPlugins(appConfig) {
-  return getServerBuildPlugins(getAppBuildManifest(appConfig));
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * Falls back through `appConfig.runtime.buildAdapter` →
+ * {@link getDefaultBuildAdapter} on the resolved ownership. Throws
+ * never; a missing adapter resolves to the global default.
+ */
+export function getAppBuildAdapter(appConfig) {
+    return appConfig.runtime?.buildAdapter ?? getDefaultBuildAdapter(getAppBuildOwnership(appConfig));
 }
-function getAppBrowserBuildPlugins(appConfig) {
-  const manifest = getAppBuildManifest(appConfig);
-  return [...getBrowserBuildPlugins(manifest), ...getJsxOwnershipPlugins(appConfig)];
+/**
+ * Installs the adapter that should serve future builds for one app
+ * instance, and aligns the ownership field to the new adapter's
+ * declared ownership.
+ */
+export function setAppBuildAdapter(appConfig, buildAdapter) {
+    patchAppRuntime(appConfig, {
+        buildOwnership: getBuildAdapterOwnership(buildAdapter),
+        buildAdapter,
+    });
 }
-function getAppBuildExecutor(appConfig) {
-  return appConfig.runtime?.routeModuleBuildExecutor ?? appConfig.runtime?.buildExecutor ?? getAppBuildAdapter(appConfig);
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ *
+ * @remarks
+ * Falls back to a fresh manifest seeded from the config's loaders when
+ * the app config has no manifest yet. This is the supported way to
+ * read the manifest across the source-loading and asset-processing
+ * services.
+ */
+export function getAppBuildManifest(appConfig) {
+    return (appConfig.runtime?.buildManifest ??
+        createAppBuildManifest({
+            loaderPlugins: Array.from(appConfig.loaders?.values() ?? []),
+        }));
 }
-function getAppHmrBuildExecutor(appConfig) {
-  return appConfig.runtime?.hmrBuildExecutor ?? getAppBuildExecutor(appConfig);
+/** Installs the build manifest that should be visible to one app instance.
+ *
+ * @remarks
+ * Production apps are sealed via {@link updateAppBuildManifest} during
+ * {@link ConfigBuilder.build}. Call `setAppBuildManifest` directly only in tests or
+ * when replacing the entire manifest object; partial updates should use
+ * {@link updateAppBuildManifest}.
+ */
+export function setAppBuildManifest(appConfig, buildManifest) {
+    patchAppRuntime(appConfig, { buildManifest });
 }
-function getAppRouteModuleBuildExecutor(appConfig) {
-  return appConfig.runtime?.routeModuleBuildExecutor ?? getAppBuildExecutor(appConfig);
+/**
+ * Builds a fresh app manifest from the config's loaders plus optional
+ * caller-supplied runtime/browser contributions.
+ *
+ * @remarks
+ * Loader plugins are always taken from the config; runtime and
+ * browser-bundle plugins are passed through from the caller when
+ * supplied, otherwise left empty for later population by
+ * {@link collectConfiguredAppBuildManifestContributions}.
+ */
+export function createConfiguredAppBuildManifest(appConfig, input) {
+    return createAppBuildManifest({
+        loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
+        runtimePlugins: input?.runtimePlugins,
+        browserBundlePlugins: input?.browserBundlePlugins,
+        browserRuntimeManifest: input?.browserRuntimeManifest,
+    });
 }
-function setAppBuildExecutor(appConfig, buildExecutor) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    buildExecutor
-  };
+/**
+ * Replaces the app-owned manifest using config-owned loaders and the
+ * caller-supplied contribution input.
+ *
+ * @remarks
+ * Primary production entry: `ConfigBuilder.build()` passes the return value of
+ * {@link collectConfiguredAppBuildManifestContributions} here to seal
+ * `appConfig.runtime.buildManifest` before startup.
+ */
+export function updateAppBuildManifest(appConfig, input) {
+    setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
 }
-function setAppHmrBuildExecutor(appConfig, buildExecutor) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    hmrBuildExecutor: buildExecutor
-  };
+export { collectConfiguredAppBuildManifestContributions, ensureIntegrationRuntimeReady, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
+/**
+ * Returns the server-bundle plugin list for one app/runtime instance.
+ *
+ * @remarks
+ * Reads from the app's sealed build manifest; the manifest itself is
+ * the source of truth for which plugins participate in the server
+ * bundle.
+ */
+export function getAppServerBuildPlugins(appConfig) {
+    const projectDir = appConfig.absolutePaths?.projectDir;
+    const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
+    return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
 }
-function setAppRouteModuleBuildExecutor(appConfig, buildExecutor) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    routeModuleBuildExecutor: buildExecutor,
-    buildExecutor
-  };
+/**
+ * Returns the browser-bundle plugin list for one app/runtime instance.
+ *
+ * @remarks
+ * 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.
+ *
+ * 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 function getAppBrowserBuildPlugins(appConfig) {
+    const manifest = getAppBuildManifest(appConfig);
+    const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
+    const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
+    const projectDir = appConfig.absolutePaths?.projectDir;
+    const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
+    return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
 }
-function build(options, executor = defaultRolldownBuildAdapter) {
-  return executor.build(options).then((result) => {
-    if (result.success) {
-      normalizeNodeRuntimeBuildOutputs(
-        result.outputs.map((output) => output.path),
-        options.root ?? process.cwd()
-      );
-    }
-    return result;
-  });
+/**
+ * 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 a profile executor from
+ * {@link requireBuildRuntime} to honor the per-app pipeline.
+ */
+export function build(options, executor = defaultRolldownBuildAdapter) {
+    return executor.build(options);
 }
-function getTranspileOptions(profile) {
-  return defaultRolldownBuildAdapter.getTranspileOptions(profile);
+/**
+ * Default transpile-options helper for callsites without app runtime
+ * context.
+ *
+ * @remarks
+ * New app-aware code should prefer {@link getAppTranspileOptions}.
+ */
+export function getTranspileOptions(profile) {
+    return defaultRolldownBuildAdapter.getTranspileOptions(profile);
 }
-function getAppTranspileOptions(appConfig, profile) {
-  return getAppBuildAdapter(appConfig).getTranspileOptions(profile);
+/**
+ * Resolves transpile options for one app/runtime instance by asking
+ * the app's adapter.
+ */
+export function getAppTranspileOptions(appConfig, profile) {
+    return getAppBuildAdapter(appConfig).getTranspileOptions(profile);
 }
-export {
-  ViteHostBuildAdapter,
-  build,
-  collectConfiguredAppBuildManifestContributions,
-  createBuildAdapter,
-  createConfiguredAppBuildManifest,
-  createViteHostBuildAdapter,
-  defaultBuildAdapter,
-  defaultRolldownBuildAdapter,
-  defaultViteHostBuildAdapter,
-  getAppBrowserBuildPlugins,
-  getAppBuildAdapter,
-  getAppBuildExecutor,
-  getAppBuildManifest,
-  getAppBuildOwnership,
-  getAppHmrBuildExecutor,
-  getAppRouteModuleBuildExecutor,
-  getAppServerBuildPlugins,
-  getAppTranspileOptions,
-  getBuildAdapterOwnership,
-  getDefaultBuildAdapter,
-  getTranspileOptions,
-  setAppBuildAdapter,
-  setAppBuildExecutor,
-  setAppBuildManifest,
-  setAppBuildOwnership,
-  setAppHmrBuildExecutor,
-  setAppRouteModuleBuildExecutor,
-  setupAppRuntimePlugins,
-  updateAppBuildManifest,
-  withBuildExecutorPlugins
-};

package/src/build/{build-input-fingerprint.d.ts → cache/build-input-fingerprint.d.ts}

@@ -1,6 +1,6 @@
-import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
-import type { Processor } from '../plugins/processor.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+import type { Processor } from '../../plugins/processor.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * Optional contributor surface for build-time cache invalidation.
  *

package/src/build/cache/build-input-fingerprint.js

@@ -0,0 +1,33 @@
+import { fileSystem } from '@ecopages/file-system';
+/** Returns whether a processor or integration signals changed build inputs. */
+export function didBuildInputContributorChange(contributor) {
+    return contributor.didChange?.() === true;
+}
+/** Hashes the app's eco.config.ts file when present. */
+export function hashAppConfigFile(appConfig) {
+    const configPath = appConfig.absolutePaths?.config;
+    if (!configPath || !fileSystem.exists(configPath)) {
+        return 'missing';
+    }
+    return fileSystem.hash(configPath);
+}
+/** Fingerprints processor/integration build-input state for cache invalidation. */
+export function createBuildInputsFingerprint(appConfig) {
+    const changedContributors = [
+        ...Array.from(appConfig.processors?.values() ?? [])
+            .filter((processor) => didBuildInputContributorChange(processor))
+            .map((processor) => `processor:${processor.getName()}`),
+        ...(appConfig.integrations ?? [])
+            .filter((integration) => didBuildInputContributorChange(integration))
+            .map((integration) => `integration:${integration.name}`),
+    ];
+    return changedContributors.length > 0 ? changedContributors.sort().join('|') : 'stable';
+}
+/** Returns true when any processor or integration reports changed build inputs. */
+export function haveBuildInputsChanged(appConfig) {
+    return createBuildInputsFingerprint(appConfig) !== 'stable';
+}
+/** Collects every processor and integration that can invalidate incremental builds. */
+export function collectBuildInputContributors(appConfig) {
+    return [...Array.from(appConfig.processors?.values() ?? []), ...(appConfig.integrations ?? [])];
+}

package/src/build/cache/cache-constants.d.ts

@@ -0,0 +1,4 @@
+/** Filename written beside persisted production build artifacts that store incremental metadata. */
+export declare const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; server-entry caches share the same filename. */
+export declare const SERVER_ENTRY_BUILD_CACHE_FILENAME = ".build-cache.json";

package/src/build/cache/cache-constants.js

@@ -0,0 +1,4 @@
+/** Filename written beside persisted production build artifacts that store incremental metadata. */
+export const ROUTE_MODULE_BUILD_CACHE_FILENAME = '.build-cache.json';
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; server-entry caches share the same filename. */
+export const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;

package/src/build/cache/cache-keys.d.ts

@@ -0,0 +1,22 @@
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { BuildOptions } from '../contracts/build-contracts.js';
+/**
+ * Returns the installed `@ecopages/core` package version for cache invalidation.
+ */
+export declare function getCorePackageVersion(): string;
+/** Stable fingerprint for JSX options used in build and disk cache keys. */
+export declare function createJsxCacheKey(jsx: BuildOptions['jsx']): string;
+/** Stable fingerprint for ordered build plugins. */
+export declare function createPluginCacheKey(plugins?: EcoBuildPlugin[]): string;
+/** Stable fingerprint for ordered source transforms. */
+export declare function createSourceTransformCacheKey(sourceTransforms: BuildOptions['sourceTransforms']): string;
+/**
+ * Stable fingerprint of a function body for cache and request identity keys.
+ *
+ * @remarks
+ * Hashes `fn.toString()`. Suitable for in-process and persisted keys that must
+ * agree within one install; not stable across minifiers or renames.
+ */
+export declare function hashFunctionIdentity(fn: (...args: never[]) => unknown): string;
+/** @deprecated Use {@link hashFunctionIdentity}. */
+export declare const hashPluginSetup: typeof hashFunctionIdentity;