@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/plugins/alias-resolver-plugin.js

@@ -1,65 +1,52 @@
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
 import { AliasResolverCache } from "./alias-resolver-cache.js";
-const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
-function findResolvablePath(candidate) {
-  if (path.extname(candidate)) {
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const fileCandidate = `${candidate}${extension}`;
-    if (existsSync(fileCandidate)) {
-      return fileCandidate;
-    }
-  }
-  for (const extension of RESOLVABLE_EXTENSIONS) {
-    const indexCandidate = path.join(candidate, `index${extension}`);
-    if (existsSync(indexCandidate)) {
-      return indexCandidate;
-    }
-  }
-  return void 0;
-}
-function resolveAliasedBarrelTarget(resolvedPath) {
-  if (!path.basename(resolvedPath).startsWith("index.")) {
-    return resolvedPath;
-  }
-  const source = readFileSync(resolvedPath, "utf8").trim();
-  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
-  if (!match?.[1]?.startsWith(".")) {
-    return resolvedPath;
-  }
-  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
-  return target ?? resolvedPath;
+import { loadTsconfigPathPrefixes, resolveProjectImportPath } from "./tsconfig-import-resolver.js";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function resolveAppSourceAliasPath(srcDir, specifier) {
-  if (!specifier.startsWith("@/")) {
-    return void 0;
+function buildPathPrefixFilter(prefix) {
+  if (prefix.endsWith("/")) {
+    return new RegExp(`^${escapeRegExp(prefix)}`);
   }
-  const candidate = path.join(srcDir, specifier.slice(2));
-  const resolved = findResolvablePath(candidate);
-  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+  return new RegExp(`^${escapeRegExp(prefix)}(?:/|$)`);
 }
-function createAliasResolverPlugin(srcDir, options) {
+function createAliasResolverPlugin(projectRoot, options) {
   const cache = options?.cache ?? new AliasResolverCache();
+  const pathPrefixes = loadTsconfigPathPrefixes(projectRoot);
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
-      build.onResolve({ filter: /^@\// }, (args) => {
-        const cached = cache.get(srcDir, args.path);
-        if (cached.hit) {
-          return cached.resolved ? { path: cached.resolved } : {};
-        }
-        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
-        cache.set(srcDir, args.path, resolved);
-        return resolved ? { path: resolved } : {};
-      });
+      if (pathPrefixes.length === 0) {
+        return;
+      }
+      for (const prefix of pathPrefixes) {
+        build.onResolve({ filter: buildPathPrefixFilter(prefix) }, (args) => {
+          if (!args.importer) {
+            return void 0;
+          }
+          const cached = cache.get(projectRoot, args.path);
+          if (cached.hit) {
+            return cached.resolved ? { path: cached.resolved } : void 0;
+          }
+          const resolved = resolveProjectImportPath(projectRoot, args.importer, args.path);
+          cache.set(projectRoot, args.path, resolved);
+          return resolved ? { path: resolved } : void 0;
+        });
+      }
     }
   };
 }
+import {
+  isBarePackageImportSpecifier,
+  matchesTsconfigPathPrefix,
+  loadTsconfigPathPrefixes as loadTsconfigPathPrefixes2,
+  resolveProjectImportPath as resolveProjectImportPath2,
+  resolveProjectModulePath
+} from "./tsconfig-import-resolver.js";
 export {
   createAliasResolverPlugin,
-  resolveAppSourceAliasPath
+  isBarePackageImportSpecifier,
+  loadTsconfigPathPrefixes2 as loadTsconfigPathPrefixes,
+  matchesTsconfigPathPrefix,
+  resolveProjectImportPath2 as resolveProjectImportPath,
+  resolveProjectModulePath
 };

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

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
+import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
+import type { EcoPagesElement } from '../types/public-types.js';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
+import { IntegrationPlugin, type IntegrationPluginConfig } from './integration-plugin.js';
+type RendererClass<C> = new (options: {
+    appConfig: EcoPagesAppConfig;
+    assetProcessingService: AssetProcessingService;
+    resolvedIntegrationDependencies: ProcessedAsset[];
+    rendererModules?: unknown;
+    runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+export interface DefineIntegrationDefinition<C = EcoPagesElement> extends IntegrationPluginConfig {
+    renderer: RendererClass<C>;
+}
+export interface DefinedIntegration<C = EcoPagesElement> {
+    (options?: Omit<IntegrationPluginConfig, 'name'>): IntegrationPlugin<C>;
+    Plugin: new (options?: Omit<IntegrationPluginConfig, 'name'>) => IntegrationPlugin<C>;
+}
+/**
+ * Creates a typed integration plugin factory for integrations that only need
+ * declarative config and a renderer class.
+ */
+export declare function defineIntegration<C = EcoPagesElement>(definition: DefineIntegrationDefinition<C>): DefinedIntegration<C>;
+export {};

package/src/plugins/define-integration.js

@@ -0,0 +1,19 @@
+import { IntegrationPlugin } from "./integration-plugin.js";
+function defineIntegration(definition) {
+  const { renderer, ...defaultConfig } = definition;
+  class DefinedIntegrationPlugin extends IntegrationPlugin {
+    renderer = renderer;
+    constructor(options) {
+      super({
+        ...defaultConfig,
+        ...options
+      });
+    }
+  }
+  const factory = ((options) => new DefinedIntegrationPlugin(options));
+  factory.Plugin = DefinedIntegrationPlugin;
+  return factory;
+}
+export {
+  defineIntegration
+};

package/src/plugins/eco-component-meta-plugin.d.ts

@@ -25,7 +25,7 @@
  *
  * @module eco-component-meta-plugin
  */
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
 /**

package/src/plugins/eco-component-meta-plugin.js

@@ -1,4 +1,5 @@
 import { cachedParseSync } from "../cache/module-parse-cache.js";
+import { prependJsxImportSourceIfMissing } from "./jsx-import-source.utils.js";
 import { rapidhash } from "../utils/hash.js";
 import {
   createEcoBuildPluginFromSourceTransform,
@@ -38,13 +39,6 @@ function detectIntegration(filePath, extensionToIntegration) {
   }
   return { name: "ghtml" };
 }
-function prependJsxImportSource(code, jsxImportSource) {
-  if (!jsxImportSource || code.includes("@jsxImportSource")) {
-    return code;
-  }
-  return `/** @jsxImportSource ${jsxImportSource} */
-${code}`;
-}
 function createExtensionPattern(extensions) {
   if (extensions.length === 0) {
     throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
@@ -67,7 +61,10 @@ function createEcoComponentMetaTransform(options) {
     transform(code, id) {
       const integration = detectIntegration(id, extensionToIntegration);
       return {
-        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
+        code: prependJsxImportSourceIfMissing(
+          injectEcoMeta(code, id, integration.name),
+          integration.jsxImportSource
+        )
       };
     }
   };

package/src/plugins/foreign-jsx-override-plugin.d.ts

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 /**
  * Options for the shared foreign-JSX override build plugin.
  */

package/src/plugins/foreign-jsx-override-plugin.js

@@ -1,10 +1,9 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { createJsxImportSourcePragma, filterJsxSourceExtensions } from "./jsx-import-source.utils.js";
 function createForeignJsxOverridePlugin(options) {
-  const extensions = options.foreignExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
-  const excludedExtensions = (options.excludeExtensions ?? []).filter(
-    (ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx")
-  );
+  const extensions = filterJsxSourceExtensions(options.foreignExtensions);
+  const excludedExtensions = filterJsxSourceExtensions(options.excludeExtensions ?? []);
   if (extensions.length === 0) {
     return {
       name: options.name ?? "foreign-jsx-override",
@@ -12,8 +11,7 @@ function createForeignJsxOverridePlugin(options) {
       }
     };
   }
-  const pragma = `/** @jsxImportSource ${options.hostJsxImportSource} */
-`;
+  const pragma = createJsxImportSourcePragma(options.hostJsxImportSource);
   const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
   return {
     name: options.name ?? "foreign-jsx-override",

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

@@ -1,15 +1,17 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import { type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
+import { type BrowserRuntimeManifest } from '../build/browser/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 { StaticExportContext } from '../static-site-generator/static-export-context.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 { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/contracts/build-types.js';
 export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { StaticExportContext } from '../static-site-generator/static-export-context.js';
 export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
 /**
  * Type-erased integration plugin stored in app-level registries.
@@ -47,13 +49,6 @@ export interface IntegrationPluginConfig {
      * They are not specific to any particular page or component.
      */
     integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
     /**
      * Declares runtime-specific requirements that must be satisfied before the
      * app can start with this integration enabled.
@@ -87,8 +82,11 @@ type RendererClass<C> = new (options: {
  *
  * Core owns lifecycle ordering. Integrations declare contributions through the
  * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
- * those hooks run. For page-browser and document shaping, integrations should
- * prefer the contribution contracts re-exported from this module:
+ * those hooks run. Build plugins map to {@link AppBuildManifest} buckets:
+ * `plugins` → `runtimePlugins`, `browserBuildPlugins` → `browserBundlePlugins`,
+ * `browserRuntimeManifest` → client import rewrite map. For page-browser and
+ * document shaping, integrations should prefer the contribution contracts
+ * re-exported from this module:
  * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
  * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
  */
@@ -96,7 +94,6 @@ 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[];
@@ -106,6 +103,14 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     protected assetProcessingService?: AssetProcessingService;
     protected hmrManager?: IHmrManager;
     runtimeOrigin: string;
+    /**
+     * Returns build plugins shared by server-oriented and browser-oriented builds.
+     *
+     * @remarks
+     * Collected into {@link AppBuildManifest.runtimePlugins} during config finalization.
+     * MDX loaders, virtual-module resolvers, and other transforms that must run during
+     * route-module transpile belong here—not in {@link browserBuildPlugins}.
+     */
     get plugins(): EcoBuildPlugin[];
     /**
      * Returns build plugins that should only apply to browser-oriented bundles.
@@ -199,11 +204,18 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * 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>;
+    /**
+     * Shapes one dependency batch before core asset processing runs.
+     *
+     * @remarks
+     * Integrations use this to assign grouped-build metadata or other batch-level
+     * policy without teaching core about integration-specific asset graphs.
+     */
+    prepareAssetDependencies?(dependencies: AssetDefinition[]): AssetDefinition[];
     /**
      * Prepares build-facing contributions before the app build manifest is sealed.
      *
@@ -213,6 +225,23 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this integration's build inputs changed since the last
+     * incremental static build.
+     */
+    didChange(): boolean;
+    /**
+     * Runs integration-specific setup before static page generation begins.
+     *
+     * @remarks
+     * Integrations that need build-scoped SSR preload or worker sessions should
+     * start them here rather than per-page inside the renderer.
+     */
+    beforeStaticExport?(_context: StaticExportContext): Promise<void>;
+    /**
+     * Releases resources started in {@link beforeStaticExport}.
+     */
+    afterStaticExport?(_context: StaticExportContext): Promise<void>;
     /**
      * Performs runtime-only integration setup after config build has already
      * sealed manifest contributions.

package/src/plugins/integration-plugin.js

@@ -1,4 +1,6 @@
-import { createBrowserRuntimeManifest } from "../build/browser-runtime-manifest.js";
+import {
+  createBrowserRuntimeManifest
+} from "../build/browser/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";
@@ -15,7 +17,6 @@ function assertIntegrationInvariant(condition, message) {
 class IntegrationPlugin {
   name;
   extensions;
-  staticBuildStep;
   runtimeCapability;
   jsxImportSource;
   integrationDependencies;
@@ -24,6 +25,14 @@ class IntegrationPlugin {
   appConfig;
   assetProcessingService;
   hmrManager;
+  /**
+   * Returns build plugins shared by server-oriented and browser-oriented builds.
+   *
+   * @remarks
+   * Collected into {@link AppBuildManifest.runtimePlugins} during config finalization.
+   * MDX loaders, virtual-module resolvers, and other transforms that must run during
+   * route-module transpile belong here—not in {@link browserBuildPlugins}.
+   */
   get plugins() {
     return [];
   }
@@ -60,7 +69,6 @@ class IntegrationPlugin {
     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;
   }
@@ -152,7 +160,6 @@ class IntegrationPlugin {
    * 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));
@@ -169,6 +176,13 @@ class IntegrationPlugin {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this integration's build inputs changed since the last
+   * incremental static build.
+   */
+  didChange() {
+    return false;
+  }
   /**
    * Performs runtime-only integration setup after config build has already
    * sealed manifest contributions.
@@ -180,7 +194,6 @@ class IntegrationPlugin {
       this.integrationDependencies,
       this.name
     );
-    this.initializeRenderer();
   }
   /**
    * Releases runtime resources owned by the integration.

package/src/plugins/jsx-import-source.utils.d.ts

@@ -0,0 +1,8 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export declare function createJsxImportSourcePragma(jsxImportSource: string): string;
+export declare function prependJsxImportSourceIfMissing(code: string, jsxImportSource: string | undefined): string;
+export declare function isJsxSourceExtension(extension: string): boolean;
+export declare function filterJsxSourceExtensions(extensions: string[]): string[];
+export declare function collectJsxExtensions(integrations: NonNullable<EcoPagesAppConfig['integrations']>, options?: {
+    excludeIntegrationName?: string;
+}): string[];

package/src/plugins/jsx-import-source.utils.js

@@ -0,0 +1,26 @@
+function createJsxImportSourcePragma(jsxImportSource) {
+  return `/** @jsxImportSource ${jsxImportSource} */
+`;
+}
+function prependJsxImportSourceIfMissing(code, jsxImportSource) {
+  if (!jsxImportSource || code.includes("@jsxImportSource")) {
+    return code;
+  }
+  return createJsxImportSourcePragma(jsxImportSource) + code;
+}
+function isJsxSourceExtension(extension) {
+  return extension.endsWith(".tsx") || extension.endsWith(".jsx");
+}
+function filterJsxSourceExtensions(extensions) {
+  return extensions.filter(isJsxSourceExtension);
+}
+function collectJsxExtensions(integrations, options) {
+  return integrations.filter((integration) => integration.jsxImportSource).filter((integration) => integration.name !== options?.excludeIntegrationName).flatMap((integration) => filterJsxSourceExtensions(integration.extensions));
+}
+export {
+  collectJsxExtensions,
+  createJsxImportSourcePragma,
+  filterJsxSourceExtensions,
+  isJsxSourceExtension,
+  prependJsxImportSourceIfMissing
+};

package/src/plugins/processor.d.ts

@@ -1,19 +1,32 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.js';
-import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.js';
+import { GENERATED_BASE_PATHS } from '../config/constants.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 { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/contracts/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 declare function resolveGeneratedPath(type: keyof typeof GENERATED_BASE_PATHS, options: {
+    root: string;
+    module: string;
+    subPath?: string;
+}): string;
 export interface ProcessorWatchContext {
     path: string;
     bridge: IClientBridge;
 }
 export interface ProcessorWatchConfig {
     paths: string[];
+    /**
+     * File extensions that trigger watch callbacks (`onCreate`, `onChange`, `onDelete`).
+     *
+     * @remarks
+     * Watch extensions drive notifications only. They do not declare asset ownership.
+     * Ownership requires {@link ProcessorConfig.capabilities} and controls whether dev
+     * invalidation skips server modules and HMR for processor-handled assets.
+     */
     extensions?: string[];
     onCreate?: (ctx: ProcessorWatchContext) => Promise<void>;
     onChange?: (ctx: ProcessorWatchContext) => Promise<void>;
@@ -52,22 +65,41 @@ export interface ProcessorContext {
     cache?: string;
 }
 /**
- * Interface for processor build plugins
- * This is used to pass plugins to the build process directly from the processor
- * For instance it can become very handy when dealing with virtual modules that needs to be recognized by the bundler
- * i.e. @ecopages/image-processor
+ * Base class for content and asset processors that contribute build plugins.
+ *
+ * @remarks
+ * Processors declare plugins through two getters that map to
+ * {@link AppBuildManifest} buckets (names differ from integrations):
+ *
+ * - `plugins` → `runtimePlugins` (server **and** browser builds)
+ * - `buildPlugins` → `browserBundlePlugins` (browser bundles only)
+ *
+ * Virtual modules that must resolve during route-module transpile belong in
+ * `plugins`. Browser-only bundler hooks belong in `buildPlugins`.
  */
 export declare abstract class Processor<TOptions = Record<string, unknown>> {
     readonly name: string;
-    protected dependencies: AssetDefinition[];
     protected context?: ProcessorContext;
     protected options?: TOptions;
     protected watchConfig?: ProcessorWatchConfig;
     protected capabilities: ProcessorAssetCapability[];
     readonly runtimeCapability?: RuntimeCapabilityDeclaration;
-    /** Plugins that are only used during the build process */
+    /**
+     * Browser-bundle-only plugins.
+     *
+     * @remarks
+     * Maps to {@link AppBuildManifest.browserBundlePlugins}. Integrations name the
+     * same bucket `browserBuildPlugins`.
+     */
     abstract buildPlugins?: EcoBuildPlugin[];
-    /** Plugins that are used during runtime for file processing */
+    /**
+     * Shared build plugins for server-oriented and browser-oriented work.
+     *
+     * @remarks
+     * Maps to {@link AppBuildManifest.runtimePlugins}. Despite the name, these are
+     * bundler plugins—not dev-server file processors. Runtime-only setup stays in
+     * {@link setup}.
+     */
     abstract plugins?: EcoBuildPlugin[];
     constructor(config: ProcessorConfig<TOptions>);
     setContext(appConfig: EcoPagesAppConfig): void;
@@ -80,14 +112,31 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Reports whether this processor's build inputs changed since the last
+     * incremental static build.
+     *
+     * @remarks
+     * No shipped processor overrides this today. Integrations and processors can
+     * opt in when they own build inputs that should invalidate incremental static
+     * exports without a full rebuild.
+     */
+    didChange(): boolean;
     abstract setup(): Promise<void>;
-    abstract teardown(): Promise<void>;
     abstract process(input: unknown, filePath?: string): Promise<unknown>;
+    /**
+     * Releases runtime resources owned by the processor.
+     *
+     * @remarks
+     * Core does not call this hook today. Override only when a processor owns
+     * watchers, compiler handles, or other resources that outlive individual
+     * requests.
+     */
+    teardown(): Promise<void>;
     protected getCachePath(key: string): string;
     protected readCache<T>(key: string): Promise<T | null>;
     protected writeCache<T>(key: string, data: T): Promise<void>;
     getWatchConfig(): ProcessorWatchConfig | undefined;
-    getDependencies(): AssetDefinition[];
     getName(): string;
     getAssetCapabilities(): ProcessorAssetCapability[];
     matchesFileFilter(_filepath: string): boolean;

package/src/plugins/processor.js

@@ -16,7 +16,6 @@ function resolveGeneratedPath(type, options) {
 }
 class Processor {
   name;
-  dependencies = [];
   context;
   options;
   watchConfig;
@@ -54,6 +53,28 @@ class Processor {
    */
   async prepareBuildContributions() {
   }
+  /**
+   * Reports whether this processor's build inputs changed since the last
+   * incremental static build.
+   *
+   * @remarks
+   * No shipped processor overrides this today. Integrations and processors can
+   * opt in when they own build inputs that should invalidate incremental static
+   * exports without a full rebuild.
+   */
+  didChange() {
+    return false;
+  }
+  /**
+   * Releases runtime resources owned by the processor.
+   *
+   * @remarks
+   * Core does not call this hook today. Override only when a processor owns
+   * watchers, compiler handles, or other resources that outlive individual
+   * requests.
+   */
+  async teardown() {
+  }
   getCachePath(key) {
     return `${this.context?.cache}/${key}`;
   }
@@ -76,9 +97,6 @@ class Processor {
   getWatchConfig() {
     return this.watchConfig;
   }
-  getDependencies() {
-    return this.dependencies;
-  }
   getName() {
     return this.name;
   }
@@ -137,5 +155,6 @@ class Processor {
 export {
   PROCESSOR_ERRORS,
   Processor,
-  mergeProcessorOptions
+  mergeProcessorOptions,
+  resolveGeneratedPath
 };