@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

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,41 @@ export declare abstract class Processor<TOptions = Record<string, unknown>> {
      * warming or watcher registration should stay in `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
+    /**
+     * Declares watch-mode SSR prewarm pathnames and readiness for core.
+     *
+     * @remarks
+     * Processors return paths and readiness only; core owns parallel rendering and page cache population.
+     */
+    collectDevPrewarmPlan(): Promise<{
+        pathnames: readonly string[];
+        readiness: 'background' | 'beforeReady';
+    }>;
+    /**
+     * 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

@@ -1,141 +1,179 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
-import { GENERATED_BASE_PATHS } from "../config/constants.js";
-import { deepMerge } from "../utils/deep-merge.js";
-const PROCESSOR_ERRORS = {
-  CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context"
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../config/constants.js';
+import { GENERATED_BASE_PATHS } from '../config/constants.js';
+import { deepMerge } from '../utils/deep-merge.js';
+export const PROCESSOR_ERRORS = {
+    CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
 };
-function mergeProcessorOptions(defaults, overrides) {
-  return deepMerge(defaults, overrides);
+export function mergeProcessorOptions(defaults, overrides) {
+    return deepMerge(defaults, overrides);
 }
-function resolveGeneratedPath(type, options) {
-  const { root, module, subPath } = options;
-  const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
-  return path.join(...parts);
+export function resolveGeneratedPath(type, options) {
+    const { root, module, subPath } = options;
+    const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
+    return path.join(...parts);
 }
-class Processor {
-  name;
-  dependencies = [];
-  context;
-  options;
-  watchConfig;
-  capabilities = [];
-  runtimeCapability;
-  constructor(config) {
-    this.name = config.name;
-    this.options = config.options;
-    this.watchConfig = config.watch;
-    this.capabilities = config.capabilities ?? [];
-    this.runtimeCapability = config.runtimeCapability;
-  }
-  setContext(appConfig) {
-    const workDir = appConfig.absolutePaths.workDir ?? path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
-    const cachePath = resolveGeneratedPath("cache", {
-      root: workDir,
-      module: this.name
-    });
-    fileSystem.ensureDir(cachePath);
-    this.context = {
-      config: appConfig,
-      rootDir: appConfig.rootDir,
-      srcDir: appConfig.absolutePaths.srcDir,
-      distDir: appConfig.absolutePaths.distDir,
-      cache: cachePath
-    };
-  }
-  /**
-   * Prepares build-facing processor contributions before config finalization.
-   *
-   * @remarks
-   * Override this when a processor must compute runtime/build plugins or other
-   * manifest-owned state before startup. Runtime-only work such as cache
-   * warming or watcher registration should stay in `setup()`.
-   */
-  async prepareBuildContributions() {
-  }
-  getCachePath(key) {
-    return `${this.context?.cache}/${key}`;
-  }
-  async readCache(key) {
-    const cachePath = this.getCachePath(key);
-    try {
-      const data = await fileSystem.readFile(cachePath);
-      return JSON.parse(data);
-    } catch {
-      return null;
+/**
+ * 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 class Processor {
+    name;
+    context;
+    options;
+    watchConfig;
+    capabilities = [];
+    runtimeCapability;
+    constructor(config) {
+        this.name = config.name;
+        this.options = config.options;
+        this.watchConfig = config.watch;
+        this.capabilities = config.capabilities ?? [];
+        this.runtimeCapability = config.runtimeCapability;
     }
-  }
-  async writeCache(key, data) {
-    if (!this.context?.cache) {
-      throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+    setContext(appConfig) {
+        const workDir = appConfig.absolutePaths.workDir ??
+            path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+        const cachePath = resolveGeneratedPath('cache', {
+            root: workDir,
+            module: this.name,
+        });
+        fileSystem.ensureDir(cachePath);
+        this.context = {
+            config: appConfig,
+            rootDir: appConfig.rootDir,
+            srcDir: appConfig.absolutePaths.srcDir,
+            distDir: appConfig.absolutePaths.distDir,
+            cache: cachePath,
+        };
     }
-    const cachePath = this.getCachePath(key);
-    fileSystem.write(cachePath, JSON.stringify(data, null, 2));
-  }
-  getWatchConfig() {
-    return this.watchConfig;
-  }
-  getDependencies() {
-    return this.dependencies;
-  }
-  getName() {
-    return this.name;
-  }
-  getAssetCapabilities() {
-    return this.capabilities;
-  }
-  matchesFileFilter(_filepath) {
-    return true;
-  }
-  canProcessAsset(kind, filepath) {
-    const capabilities = this.getAssetCapabilities();
-    if (capabilities.length === 0) {
-      return false;
+    /**
+     * Prepares build-facing processor contributions before config finalization.
+     *
+     * @remarks
+     * Override this when a processor must compute runtime/build plugins or other
+     * manifest-owned state before startup. Runtime-only work such as cache
+     * warming or watcher registration should stay in `setup()`.
+     */
+    async prepareBuildContributions() { }
+    /**
+     * Declares watch-mode SSR prewarm pathnames and readiness for core.
+     *
+     * @remarks
+     * Processors return paths and readiness only; core owns parallel rendering and page cache population.
+     */
+    collectDevPrewarmPlan() {
+        return Promise.resolve({ pathnames: [], readiness: 'background' });
     }
-    const matchingKind = capabilities.filter((capability) => capability.kind === kind);
-    if (matchingKind.length === 0) {
-      return false;
+    /**
+     * 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;
     }
-    if (!filepath) {
-      return true;
+    /**
+     * 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}`;
     }
-    return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
-  }
-  matchesCapabilityExtensions(filepath, extensions) {
-    if (!extensions || extensions.length === 0) {
-      return true;
+    async readCache(key) {
+        const cachePath = this.getCachePath(key);
+        try {
+            const data = await fileSystem.readFile(cachePath);
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
     }
-    const normalizedExt = path.extname(filepath).toLowerCase();
-    return extensions.some((rawPattern) => {
-      const pattern = this.normalizeExtensionPattern(rawPattern);
-      if (!pattern) {
-        return false;
-      }
-      if (pattern === "*") {
+    async writeCache(key, data) {
+        if (!this.context?.cache) {
+            throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+        }
+        const cachePath = this.getCachePath(key);
+        fileSystem.write(cachePath, JSON.stringify(data, null, 2));
+    }
+    getWatchConfig() {
+        return this.watchConfig;
+    }
+    getName() {
+        return this.name;
+    }
+    getAssetCapabilities() {
+        return this.capabilities;
+    }
+    matchesFileFilter(_filepath) {
         return true;
-      }
-      const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
-      if (groupedMatch) {
-        const groupItems = groupedMatch[1].split(",").map((item) => this.normalizeExtensionPattern(item)).filter(Boolean);
-        return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
-      }
-      if (pattern.startsWith("*")) {
-        const suffix = pattern.slice(1);
-        return normalizedExt.endsWith(suffix);
-      }
-      if (pattern.startsWith(".")) {
-        return normalizedExt === pattern;
-      }
-      return normalizedExt === `.${pattern}`;
-    });
-  }
-  normalizeExtensionPattern(rawPattern) {
-    return rawPattern.trim().toLowerCase();
-  }
+    }
+    canProcessAsset(kind, filepath) {
+        const capabilities = this.getAssetCapabilities();
+        if (capabilities.length === 0) {
+            return false;
+        }
+        const matchingKind = capabilities.filter((capability) => capability.kind === kind);
+        if (matchingKind.length === 0) {
+            return false;
+        }
+        if (!filepath) {
+            return true;
+        }
+        return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
+    }
+    matchesCapabilityExtensions(filepath, extensions) {
+        if (!extensions || extensions.length === 0) {
+            return true;
+        }
+        const normalizedExt = path.extname(filepath).toLowerCase();
+        return extensions.some((rawPattern) => {
+            const pattern = this.normalizeExtensionPattern(rawPattern);
+            if (!pattern) {
+                return false;
+            }
+            if (pattern === '*') {
+                return true;
+            }
+            const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
+            if (groupedMatch) {
+                const groupItems = groupedMatch[1]
+                    .split(',')
+                    .map((item) => this.normalizeExtensionPattern(item))
+                    .filter(Boolean);
+                return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
+            }
+            if (pattern.startsWith('*')) {
+                const suffix = pattern.slice(1);
+                return normalizedExt.endsWith(suffix);
+            }
+            if (pattern.startsWith('.')) {
+                return normalizedExt === pattern;
+            }
+            return normalizedExt === `.${pattern}`;
+        });
+    }
+    normalizeExtensionPattern(rawPattern) {
+        return rawPattern.trim().toLowerCase();
+    }
 }
-export {
-  PROCESSOR_ERRORS,
-  Processor,
-  mergeProcessorOptions
-};

package/src/plugins/runtime-capability.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,12 +1,24 @@
-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';
 export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
  */
 export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**