@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

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

@@ -0,0 +1,97 @@
+/**
+ * Bun plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin uses AST parsing (via oxc-parser) to reliably inject the `__eco` property
+ * into EcoComponent config objects at import time. The injected metadata contains:
+ * - `dir`: The directory path of the component file (used for dependency resolution)
+ * - `integration`: The integration type (e.g., 'react', 'kitajs', 'ghtml', 'lit')
+ *
+ * The plugin intercepts file loading for all configured integration extensions and
+ * transforms component configs before they are executed.
+ *
+ * @example
+ * ```typescript
+ * // Before transformation:
+ * export default eco.page({
+ *   render: () => '<div>Hello</div>',
+ * });
+ *
+ * // After transformation:
+ * export default eco.page({
+ *   __eco: { id: "<hash>", file: "/path/to/pages/index.tsx", integration: "react" },
+ *   render: () => '<div>Hello</div>',
+ * });
+ * ```
+ *
+ * @module eco-component-meta-plugin
+ */
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig } from '../internal-types.js';
+/**
+ * Options for creating the eco-component-meta-plugin.
+ */
+export interface EcoComponentDirPluginOptions {
+    /** The EcoPages application configuration containing integration settings */
+    config: EcoPagesAppConfig;
+}
+/**
+ * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin intercepts file loading for all integration-compatible files and:
+ * 1. Strips any query string from the file path (for dev mode cache-busting)
+ * 2. Reads the file contents
+ * 3. Parses the AST using oxc-parser to find injection points
+ * 4. Injects `__eco: { id: "...", file: "...", integration: "..." }` into config objects
+ * 5. Returns the transformed content with the appropriate loader
+ *
+ * Supported patterns:
+ * - `eco.page({ ... })` - Page component declarations
+ * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
+ * - `Component.config = { ... }` - Config assignment pattern
+ * - `config: { ... }` - Config property in object literals
+ * - `export const config = { ... }` - Exported config declarations
+ *
+ * @param options - Plugin options containing the EcoPages config
+ * @returns A build plugin instance ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { createEcoComponentMetaPlugin } from '@ecopages/core';
+ *
+ * const plugin = createEcoComponentMetaPlugin({ config: appConfig });
+ * appConfig.loaders.set(plugin.name, plugin);
+ * ```
+ */
+export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
+/**
+ * Injects `__eco` metadata into EcoComponent config objects in file content.
+ *
+ * Uses oxc-parser for robust AST-based code analysis, which handles edge cases
+ * that regex-based approaches would miss (e.g., complex generics, nested objects,
+ * comments, string literals containing similar patterns).
+ *
+ * The injection is performed by:
+ * 1. Parsing the source code into an AST
+ * 2. Walking the AST to find all config object patterns
+ * 3. Collecting insertion points (sorted in reverse order to preserve positions)
+ * 4. Inserting the `__eco` property at each point
+ *
+ * @param contents - The source code content to transform
+ * @param filePath - Absolute path to the file (used to derive the directory)
+ * @param integration - The integration identifier for this file type
+ * @returns Transformed source code with `__eco` injected, or original if no patterns found
+ *
+ * @example
+ * ```typescript
+ * const result = injectEcoMeta(
+ *   'export default eco.page({ render: () => "<div>Hi</div>" });',
+ *   '/app/src/pages/index.tsx',
+ *   'react'
+ * );
+ * // Result: 'export default eco.page({ __eco: { id: "<hash>", file: "/app/src/pages/index.tsx", integration: "react" }, render: () => "<div>Hi</div>" });'
+ * ```
+ */
+export declare function injectEcoMeta(contents: string, filePath: string, integration: string): string;
+export default createEcoComponentMetaPlugin;

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

@@ -0,0 +1,157 @@
+import path from "node:path";
+import { parseSync } from "oxc-parser";
+import { fileSystem } from "@ecopages/file-system";
+import { rapidhash } from "../utils/hash.js";
+const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
+const VALID_LOADER_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+function hasValidLoaderExtension(ext) {
+  for (const validExt of VALID_LOADER_EXTENSIONS) {
+    if (ext.endsWith(validExt)) {
+      return true;
+    }
+  }
+  return false;
+}
+function buildExtensionToIntegrationMap(integrations) {
+  const mapping = [];
+  for (const integration of integrations) {
+    for (const ext of integration.extensions) {
+      mapping.push([ext, integration.name]);
+    }
+  }
+  mapping.sort((a, b) => b[0].length - a[0].length);
+  return mapping;
+}
+function detectIntegration(filePath, extensionToIntegration) {
+  for (const [ext, integration] of extensionToIntegration) {
+    if (filePath.endsWith(ext)) {
+      return integration;
+    }
+  }
+  return "ghtml";
+}
+function createExtensionPattern(extensions) {
+  if (extensions.length === 0) {
+    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
+  }
+  const uniqueExtensions = [...new Set(extensions)];
+  const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, "\\$&"));
+  return new RegExp(`(${escaped.join("|")})(\\?.*)?$`);
+}
+function createEcoComponentMetaPlugin(options) {
+  return {
+    name: "eco-component-meta-plugin",
+    setup(build) {
+      const allExtensions = options.config.integrations.flatMap((integration) => integration.extensions).filter(hasValidLoaderExtension);
+      if (allExtensions.length === 0) {
+        return;
+      }
+      const extensionPattern = createExtensionPattern(allExtensions);
+      const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
+      build.onLoad({ filter: extensionPattern }, (args) => {
+        const filePath = args.path.split("?")[0];
+        const contents = fileSystem.readFileSync(filePath);
+        const integration = detectIntegration(filePath, extensionToIntegration);
+        const transformedContents = injectEcoMeta(contents, filePath, integration);
+        const ext = path.extname(filePath).slice(1);
+        return {
+          contents: transformedContents,
+          loader: ext || "ts"
+        };
+      });
+    }
+  };
+}
+function findInjectionPoints(node, insertions, injection, isInsideEcoComponent = false) {
+  if (!node || typeof node !== "object") return;
+  const n = node;
+  if (n.type === "CallExpression") {
+    const callee = n.callee;
+    if (callee?.type === "MemberExpression" || callee?.type === "StaticMemberExpression") {
+      const obj = callee.object;
+      const prop = callee.property;
+      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component" || prop?.name === "html" || prop?.name === "layout")) {
+        const args = n.arguments;
+        const firstArg = args?.[0];
+        if (firstArg?.type === "ObjectExpression") {
+          const start = firstArg.start;
+          if (typeof start === "number") {
+            insertions.push({ position: start + 1, text: injection });
+          }
+        }
+      }
+    }
+  }
+  if (n.type === "AssignmentExpression") {
+    const left = n.left;
+    const right = n.right;
+    if (left?.type === "MemberExpression" || left?.type === "StaticMemberExpression") {
+      const prop = left.property;
+      if (prop?.name === "config" && right?.type === "ObjectExpression") {
+        const start = right.start;
+        if (typeof start === "number") {
+          insertions.push({ position: start + 1, text: injection });
+        }
+      }
+    }
+  }
+  if (n.type === "ObjectProperty" || n.type === "Property") {
+    const key = n.key;
+    const value = n.value;
+    if ((key?.type === "Identifier" || key?.type === "IdentifierName") && key?.name === "config" && value?.type === "ObjectExpression" && isInsideEcoComponent) {
+      const start = value.start;
+      if (typeof start === "number") {
+        insertions.push({ position: start + 1, text: injection });
+      }
+    }
+  }
+  let childIsInsideEcoComponent = isInsideEcoComponent;
+  if (n.type === "VariableDeclarator") {
+    const id = n.id;
+    const typeAnnotation = id?.typeAnnotation;
+    if (typeAnnotation) {
+      const typeStr = JSON.stringify(typeAnnotation);
+      if (typeStr.includes("EcoComponent")) {
+        childIsInsideEcoComponent = true;
+      }
+    }
+  }
+  for (const key in n) {
+    if (key === "start" || key === "end" || key === "type") continue;
+    const value = n[key];
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        findInjectionPoints(child, insertions, injection, childIsInsideEcoComponent);
+      }
+    } else if (typeof value === "object" && value !== null) {
+      findInjectionPoints(value, insertions, injection, childIsInsideEcoComponent);
+    }
+  }
+}
+function injectEcoMeta(contents, filePath, integration) {
+  const result = parseSync(filePath, contents);
+  if (result.errors.length > 0) {
+    console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
+    return contents;
+  }
+  const ast = result.program;
+  const id = rapidhash(filePath).toString(36);
+  const injection = ` __eco: { id: "${id}", file: "${filePath}", integration: "${integration}" },`;
+  const insertions = [];
+  findInjectionPoints(ast, insertions, injection);
+  if (insertions.length === 0) {
+    return contents;
+  }
+  insertions.sort((a, b) => b.position - a.position);
+  let transformed = contents;
+  for (const { position, text } of insertions) {
+    transformed = transformed.slice(0, position) + text + transformed.slice(position);
+  }
+  return transformed;
+}
+var eco_component_meta_plugin_default = createEcoComponentMetaPlugin;
+export {
+  createEcoComponentMetaPlugin,
+  eco_component_meta_plugin_default as default,
+  injectEcoMeta
+};

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

@@ -0,0 +1,136 @@
+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/orchestration/integration-renderer';
+import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service';
+import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
+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 interface IntegrationPluginConfig {
+    /**
+     * The name of the integration plugin.
+     */
+    name: string;
+    /**
+     * The extensions that this plugin supports (e.g., ['.kita.js', '.kita.tsx']).
+     */
+    extensions: string[];
+    /**
+     * The dependencies that this plugin requires on a global level.
+     * These dependencies will be resolved during the setup process and injected into the global scope of the application.
+     * 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.
+     */
+    runtimeCapability?: RuntimeCapabilityDeclaration;
+}
+/**
+ * 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[];
+    runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
+    readonly name: string;
+    readonly extensions: string[];
+    abstract renderer: RendererClass<C>;
+    readonly staticBuildStep: 'render' | 'fetch';
+    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
+    protected integrationDependencies: AssetDefinition[];
+    protected resolvedIntegrationDependencies: ProcessedAsset[];
+    protected options?: Record<string, unknown>;
+    protected appConfig?: EcoPagesAppConfig;
+    protected assetProcessingService?: AssetProcessingService;
+    protected hmrManager?: IHmrManager;
+    runtimeOrigin: string;
+    get plugins(): EcoBuildPlugin[];
+    constructor(config: IntegrationPluginConfig);
+    setConfig(appConfig: EcoPagesAppConfig): void;
+    setRuntimeOrigin(runtimeOrigin: string): void;
+    /**
+     * Returns an HMR strategy for this integration, if applicable.
+     * The strategy will be registered with the HmrManager during initialization.
+     *
+     * @returns HmrStrategy instance or undefined if no custom HMR handling needed
+     *
+     * @example
+     * ```typescript
+     * getHmrStrategy(): HmrStrategy {
+     *   const context = this.hmrManager!.getDefaultContext();
+     *   return new ReactHmrStrategy(context);
+     * }
+     * ```
+     */
+    getHmrStrategy?(): HmrStrategy | undefined;
+    /**
+     * Returns bare-specifier mappings that should be registered in the active
+     * runtime specifier registry.
+     *
+     * @remarks
+     * Override this when the integration owns browser runtime bundles that must
+     * be addressable from client-side imports through stable bare specifiers.
+     *
+     * Today these mappings are consumed by the development runtime and browser
+     * bundle aliasing path. They are intentionally generic enough to grow into a
+     * broader import-map-style facility later without moving framework-specific
+     * map contents into core.
+     */
+    getRuntimeSpecifierMap(): Record<string, string>;
+    setHmrManager(hmrManager: IHmrManager): void;
+    initializeAssetDefinitionService(): void;
+    getResolvedIntegrationDependencies(): ProcessedAsset[];
+    initializeRenderer(): IntegrationRenderer<C>;
+    /**
+     * Declares whether a component boundary targeting this integration should be
+     * deferred through the marker pipeline.
+     *
+     * 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.
+     *
+     * @param input Boundary metadata for the current render pass.
+     * @returns `true` when the boundary should be deferred; otherwise `false`.
+     */
+    shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
+    /**
+     * Prepares build-facing contributions before the app build manifest is sealed.
+     *
+     * @remarks
+     * Override this when an integration needs to materialize runtime/build plugin
+     * declarations ahead of runtime startup. Keep runtime-only side effects out of
+     * this hook; they belong in `setup()`.
+     */
+    prepareBuildContributions(): Promise<void>;
+    /**
+     * Performs runtime-only integration setup after config build has already
+     * sealed manifest contributions.
+     */
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+}

package/src/plugins/integration-plugin.js

@@ -0,0 +1,133 @@
+import { AssetProcessingService } from "../services/assets/asset-processing-service/asset-processing.service";
+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"
+};
+class IntegrationPlugin {
+  name;
+  extensions;
+  staticBuildStep;
+  runtimeCapability;
+  integrationDependencies;
+  resolvedIntegrationDependencies = [];
+  options;
+  appConfig;
+  assetProcessingService;
+  hmrManager;
+  get plugins() {
+    return [];
+  }
+  constructor(config) {
+    this.name = config.name;
+    this.extensions = config.extensions;
+    this.integrationDependencies = config.integrationDependencies || [];
+    this.staticBuildStep = config.staticBuildStep || "render";
+    this.runtimeCapability = config.runtimeCapability;
+  }
+  setConfig(appConfig) {
+    this.appConfig = appConfig;
+    this.initializeAssetDefinitionService();
+  }
+  setRuntimeOrigin(runtimeOrigin) {
+    this.runtimeOrigin = runtimeOrigin;
+  }
+  /**
+   * Returns bare-specifier mappings that should be registered in the active
+   * runtime specifier registry.
+   *
+   * @remarks
+   * Override this when the integration owns browser runtime bundles that must
+   * be addressable from client-side imports through stable bare specifiers.
+   *
+   * Today these mappings are consumed by the development runtime and browser
+   * bundle aliasing path. They are intentionally generic enough to grow into a
+   * broader import-map-style facility later without moving framework-specific
+   * map contents into core.
+   */
+  getRuntimeSpecifierMap() {
+    return {};
+  }
+  setHmrManager(hmrManager) {
+    this.hmrManager = hmrManager;
+    hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
+    const strategy = this.getHmrStrategy?.();
+    if (strategy) {
+      hmrManager.registerStrategy(strategy);
+    }
+    if (this.assetProcessingService) {
+      this.assetProcessingService.setHmrManager(hmrManager);
+    }
+  }
+  initializeAssetDefinitionService() {
+    if (!this.appConfig) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+    this.assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+    if (this.hmrManager) {
+      this.assetProcessingService.setHmrManager(this.hmrManager);
+    }
+  }
+  getResolvedIntegrationDependencies() {
+    return this.resolvedIntegrationDependencies;
+  }
+  initializeRenderer() {
+    if (!this.appConfig) {
+      throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+    }
+    const assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+    if (this.hmrManager) {
+      assetProcessingService.setHmrManager(this.hmrManager);
+    }
+    const renderer = new this.renderer({
+      appConfig: this.appConfig,
+      assetProcessingService,
+      resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
+      runtimeOrigin: this.runtimeOrigin
+    });
+    if (this.hmrManager) {
+      renderer.setHmrManager(this.hmrManager);
+    }
+    return renderer;
+  }
+  /**
+   * Declares whether a component boundary targeting this integration should be
+   * deferred through the marker pipeline.
+   *
+   * 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.
+   *
+   * @param input Boundary metadata for the current render pass.
+   * @returns `true` when the boundary should be deferred; otherwise `false`.
+   */
+  shouldDeferComponentBoundary(_input) {
+    return false;
+  }
+  /**
+   * Prepares build-facing contributions before the app build manifest is sealed.
+   *
+   * @remarks
+   * Override this when an integration needs to materialize runtime/build plugin
+   * declarations ahead of runtime startup. Keep runtime-only side effects out of
+   * this hook; they belong in `setup()`.
+   */
+  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);
+    this.resolvedIntegrationDependencies = await this.assetProcessingService.processDependencies(
+      this.integrationDependencies,
+      this.name
+    );
+    this.initializeRenderer();
+  }
+  async teardown() {
+  }
+}
+export {
+  INTEGRATION_PLUGIN_ERRORS,
+  IntegrationPlugin
+};

package/src/plugins/processor.d.ts

@@ -0,0 +1,95 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
+import type { AssetDefinition } from '../services/assets/asset-processing-service';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
+export declare const PROCESSOR_ERRORS: {
+    readonly CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context";
+};
+export interface ProcessorWatchContext {
+    path: string;
+    bridge: IClientBridge;
+}
+export interface ProcessorWatchConfig {
+    paths: string[];
+    extensions?: string[];
+    onCreate?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onChange?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onDelete?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onError?: (error: Error) => void;
+}
+export type ProcessorAssetKind = 'script' | 'stylesheet' | 'image';
+export type ProcessorExtensionPattern = string;
+export interface ProcessorAssetCapability {
+    kind: ProcessorAssetKind;
+    /**
+     * Supported patterns:
+     * - `*` (all extensions)
+     * - `.css` or `css`
+     * - `*.css`
+     * - `*.{css,scss,sass}`
+     *
+     * Pattern matching is case-insensitive and trims surrounding spaces,
+     * including grouped values (e.g. `*.{ CSS, ScSs }`).
+     */
+    extensions?: ProcessorExtensionPattern[];
+}
+export interface ProcessorConfig<TOptions = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    options?: TOptions;
+    watch?: ProcessorWatchConfig;
+    capabilities?: ProcessorAssetCapability[];
+    runtimeCapability?: RuntimeCapabilityDeclaration;
+}
+export interface ProcessorContext {
+    config: EcoPagesAppConfig;
+    rootDir: string;
+    srcDir: string;
+    distDir: string;
+    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
+ */
+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 */
+    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>;
+    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;
+    canProcessAsset(kind: ProcessorAssetKind, filepath?: string): boolean;
+    private matchesCapabilityExtensions;
+    private normalizeExtensionPattern;
+}