@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

package/src/plugins/integration-plugin.js

@@ -1,201 +0,0 @@
-import { createBrowserRuntimeManifest } from "../build/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";
-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"
-};
-function mergeIntegrationOptions(defaults, overrides) {
-  return deepMerge(defaults, overrides);
-}
-function assertIntegrationInvariant(condition, message) {
-  invariant(condition, message);
-}
-class IntegrationPlugin {
-  name;
-  extensions;
-  staticBuildStep;
-  runtimeCapability;
-  jsxImportSource;
-  integrationDependencies;
-  resolvedIntegrationDependencies = [];
-  options;
-  appConfig;
-  assetProcessingService;
-  hmrManager;
-  get plugins() {
-    return [];
-  }
-  /**
-   * Returns build plugins that should only apply to browser-oriented bundles.
-   *
-   * @remarks
-   * Browser-only transforms such as runtime import aliasing belong here so they
-   * do not affect server bundles or static-page module generation.
-   */
-  get browserBuildPlugins() {
-    return [];
-  }
-  /**
-   * Returns shared browser runtime asset declarations owned by this integration.
-   *
-   * @remarks
-   * Core seals these declarations into the app build manifest so app-owned browser
-   * bundle paths can rewrite manifest-owned imports even when a specific build
-   * request does not install an integration-local runtime rewrite plugin.
-   */
-  get browserRuntimeManifest() {
-    return createBrowserRuntimeManifest();
-  }
-  /**
-   * Creates the integration with static declaration-only configuration.
-   *
-   * @remarks
-   * Constructors are expected to stay side-effect free. Build-manifest
-   * contributions belong in `prepareBuildContributions()` and runtime-only setup
-   * belongs in `setup()`.
-   */
-  constructor(config) {
-    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;
-  }
-  /**
-   * Attaches the finalized app config to the integration.
-   *
-   * Core calls this during config finalization before runtime setup so the
-   * integration can resolve asset paths and other app-owned services later.
-   */
-  setConfig(appConfig) {
-    this.appConfig = appConfig;
-    this.initializeAssetDefinitionService();
-  }
-  /**
-   * Records the runtime origin used for page-module loading and renderer setup.
-   */
-  setRuntimeOrigin(runtimeOrigin) {
-    this.runtimeOrigin = runtimeOrigin;
-  }
-  /**
-   * Attaches the shared HMR manager and registers integration-owned development hooks.
-   *
-   * @remarks
-   * The default implementation registers the optional integration HMR strategy.
-   * Integrations should override this only when they need to extend that shared
-   * behavior rather than replace it.
-   */
-  setHmrManager(hmrManager) {
-    this.hmrManager = hmrManager;
-    const strategy = this.getHmrStrategy?.();
-    if (strategy) {
-      hmrManager.registerStrategy(strategy);
-    }
-    if (this.assetProcessingService) {
-      this.assetProcessingService.setHmrManager(hmrManager);
-    }
-  }
-  /**
-   * Creates the asset-processing service used for global integration dependencies.
-   */
-  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);
-    }
-  }
-  /**
-   * Returns processed global assets resolved during `setup()`.
-   */
-  getResolvedIntegrationDependencies() {
-    return this.resolvedIntegrationDependencies;
-  }
-  /**
-   * Creates the shared renderer options owned by core lifecycle setup.
-   */
-  createRendererOptions(options) {
-    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);
-    }
-    return {
-      appConfig: this.appConfig,
-      assetProcessingService,
-      resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
-      rendererModules: options?.rendererModules,
-      runtimeOrigin: this.runtimeOrigin
-    };
-  }
-  /**
-   * Attaches runtime-only services after a renderer instance has been created.
-   */
-  attachRendererRuntimeServices(renderer) {
-    if (typeof renderer.name !== "string" || renderer.name.length === 0) {
-      renderer.name = this.name;
-    }
-    if (this.hmrManager) {
-      renderer.setHmrManager(this.hmrManager);
-    }
-    return renderer;
-  }
-  /**
-   * Instantiates the integration renderer with app-owned services.
-   *
-   * @remarks
-   * 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));
-    renderer.name ||= this.name;
-    return this.attachRendererRuntimeServices(renderer);
-  }
-  /**
-   * Prepares build-facing contributions before the app build manifest is sealed.
-   *
-   * @remarks
-   * Integrations can override this when runtime or build plugin declarations must
-   * be materialized ahead of runtime startup. Runtime-only side effects stay 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();
-  }
-  /**
-   * Releases runtime resources owned by the integration.
-   *
-   * @remarks
-   * Most integrations do not need custom teardown. Override this only for
-   * explicit cleanup such as watchers, compiler handles, or runtime registries
-   * that outlive individual requests.
-   */
-  async teardown() {
-  }
-}
-export {
-  INTEGRATION_PLUGIN_ERRORS,
-  IntegrationPlugin,
-  assertIntegrationInvariant,
-  mergeIntegrationOptions
-};

package/src/plugins/processor.d.ts

@@ -1,97 +0,0 @@
-import type { EcoBuildPlugin } from '../build/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 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 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 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;
-}

package/src/plugins/processor.js

@@ -1,141 +0,0 @@
-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"
-};
-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);
-}
-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;
-    }
-  }
-  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;
-  }
-  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;
-    }
-    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/source-transform.d.ts

@@ -1,46 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-export interface EcoSourceTransformResult {
-    code: string;
-    map?: unknown;
-}
-export interface EcoSourceTransform {
-    name: string;
-    filter: RegExp;
-    enforce?: 'pre' | 'post';
-    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
-}
-export interface EcoViteCompatiblePlugin {
-    name: string;
-    enforce?: 'pre' | 'post';
-    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
-}
-/**
- * Normalizes bundler module ids so one transform can serve Ecopages loaders,
- * Vite, and future bundler adapters.
- */
-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;
-/**
- * Adapts a source transform into the existing Ecopages build-plugin contract.
- */
-export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
-/**
- * Adapts a source transform into a Vite-compatible plugin object.
- *
- * @remarks
- * This intentionally returns a plain object shape so core does not need a hard
- * dependency on `vite` just to author transform primitives.
- */
-export declare function createVitePluginFromSourceTransform(transform: EcoSourceTransform): EcoViteCompatiblePlugin;
-/**
- * Returns the app-owned source transforms in stable registration order.
- */
-export declare function getAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoSourceTransform[];
-/**
- * Adapts the app-owned source transforms into Vite-compatible plugin objects.
- */
-export declare function createVitePluginsFromAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoViteCompatiblePlugin[];

package/src/plugins/source-transform.js

@@ -1,71 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-function normalizeTransformId(id) {
-  const queryIndex = id.indexOf("?");
-  const hashIndex = id.indexOf("#");
-  const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
-  return endIndex === void 0 ? id : id.slice(0, endIndex);
-}
-function applySourceTransform(transform, code, id) {
-  const normalizedId = normalizeTransformId(id);
-  if (!transform.filter.test(normalizedId)) {
-    return void 0;
-  }
-  return transform.transform(code, normalizedId);
-}
-function inferLoaderFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    default:
-      return "js";
-  }
-}
-function createEcoBuildPluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    setup(build) {
-      build.onLoad({ filter: transform.filter }, (args) => {
-        const filePath = normalizeTransformId(args.path);
-        const code = fileSystem.readFileSync(filePath);
-        const result = applySourceTransform(transform, code, filePath);
-        if (!result) {
-          return void 0;
-        }
-        return {
-          contents: typeof result === "string" ? result : result.code,
-          loader: inferLoaderFromPath(filePath),
-          resolveDir: path.dirname(filePath)
-        };
-      });
-    }
-  };
-}
-function createVitePluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    enforce: transform.enforce,
-    transform(code, id) {
-      return applySourceTransform(transform, code, id);
-    }
-  };
-}
-function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
-}
-function createVitePluginsFromAppSourceTransforms(appConfig) {
-  return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
-}
-export {
-  applySourceTransform,
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  normalizeTransformId
-};

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -1,97 +0,0 @@
-import type { EcoComponent } from '../../types/public-types.js';
-/**
- * Result returned by a renderer-owned foreign-child runtime.
- *
- * `inline` keeps rendering inside the current integration. `resolved` returns a
- * renderer-owned value immediately, which can be final HTML or a renderer-local
- * transport token for later queue resolution.
- */
-export type ForeignChildInterceptionResult = {
-    kind: 'inline';
-    props?: Record<string, unknown>;
-} | {
-    kind: 'resolved';
-    value: unknown;
-};
-export type ForeignChildRenderInterception = {
-    kind: 'inline';
-    props?: Record<string, unknown>;
-} | {
-    kind: 'resolved';
-    value: unknown;
-} | undefined;
-/**
- * Foreign-child metadata passed into the active renderer-owned runtime.
- */
-export type ForeignChildInterceptionInput = {
-    currentIntegration: string;
-    targetIntegration?: string;
-    component: EcoComponent;
-    props: Record<string, unknown>;
-};
-/**
- * Narrow renderer-owned foreign-child runtime injected into one active render
- * context.
- *
- * Integrations implement this contract when foreign children must be handed
- * off inside the renderer instead of being left for route-level reconciliation.
- */
-export interface ForeignChildRuntime {
-    /**
-     * Intercepts one foreign child during an active render.
-     *
-     * This runtime is typically installed by the Foreign Subtree execution module,
-     * which decides whether the child stays inline or leaves the current renderer.
-     */
-    interceptForeignChild?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult | Promise<ForeignChildInterceptionResult>;
-    interceptForeignChildSync?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult;
-}
-type ForeignChildRenderInput = {
-    component: EcoComponent;
-    props: Record<string, unknown>;
-    targetIntegration?: string;
-};
-/**
- * Per-render mutable state used while applying foreign-child interception and lazy
- * output wrapping.
- */
-export type ComponentRenderContext = {
-    currentIntegration: string;
-    foreignChildRuntime?: ForeignChildRuntime;
-    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
-    finalizeComponentRender<T>(component: EcoComponent, content: T): T;
-};
-/**
- * Returns the current component render context, if one is active.
- *
- * @returns Active render context or `undefined` outside render execution.
- */
-export declare function getComponentRenderContext(): ComponentRenderContext | undefined;
-/**
- * Runs foreign-child interception for one component render step.
- *
- * The active runtime may resolve the foreign child immediately or keep it inline.
- */
-export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
-/**
- * Applies lazy trigger or injector wrapping to completed component output.
- *
- * This helper works both inside render-context execution and in fallback flows
- * where no active context exists.
- */
-export declare function finalizeComponentRender<T>(component: EcoComponent, content: T): T;
-/**
- * Runs render work under a fresh component render context and returns the
- * resulting value.
- *
- * @param input Execution metadata for current integration and foreign-child policy.
- * @param render Async render function to execute inside the context.
- * @returns Render result value.
- */
-export declare function runWithComponentRenderContext<T>(input: {
-    currentIntegration: string;
-    foreignChildRuntime?: ForeignChildRuntime;
-}, render: () => Promise<T>): Promise<{
-    value: T;
-}>;
-export {};