@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

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

@@ -1,5 +1,6 @@
 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)) {
@@ -33,21 +34,32 @@ function resolveAliasedBarrelTarget(resolvedPath) {
   const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
   return target ?? resolvedPath;
 }
-function createAliasResolverPlugin(srcDir) {
+function resolveAppSourceAliasPath(srcDir, specifier) {
+  if (!specifier.startsWith("@/")) {
+    return void 0;
+  }
+  const candidate = path.join(srcDir, specifier.slice(2));
+  const resolved = findResolvablePath(candidate);
+  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+}
+function createAliasResolverPlugin(srcDir, options) {
+  const cache = options?.cache ?? new AliasResolverCache();
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
       build.onResolve({ filter: /^@\// }, (args) => {
-        const candidate = path.join(srcDir, args.path.slice(2));
-        const resolved = findResolvablePath(candidate);
-        if (resolved) {
-          return { path: resolveAliasedBarrelTarget(resolved) };
+        const cached = cache.get(srcDir, args.path);
+        if (cached.hit) {
+          return cached.resolved ? { path: cached.resolved } : {};
         }
-        return {};
+        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
+        cache.set(srcDir, args.path, resolved);
+        return resolved ? { path: resolved } : {};
       });
     }
   };
 }
 export {
-  createAliasResolverPlugin
+  createAliasResolverPlugin,
+  resolveAppSourceAliasPath
 };

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

@@ -26,7 +26,8 @@
  * @module eco-component-meta-plugin
  */
 import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
 /**
  * Options for creating the eco-component-meta-plugin.
  */
@@ -34,6 +35,11 @@ export interface EcoComponentDirPluginOptions {
     /** The EcoPages application configuration containing integration settings */
     config: EcoPagesAppConfig;
 }
+/**
+ * Creates the bundler-neutral metadata transform used by Ecopages loaders and
+ * Vite-compatible adapters.
+ */
+export declare function createEcoComponentMetaTransform(options: EcoComponentDirPluginOptions): EcoSourceTransform;
 /**
  * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
  *
@@ -65,6 +71,11 @@ export interface EcoComponentDirPluginOptions {
  * ```
  */
 export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
+/**
+ * Creates a Vite-compatible metadata injection plugin from the shared
+ * Ecopages source-transform primitive.
+ */
+export declare function createEcoComponentMetaVitePlugin(options: EcoComponentDirPluginOptions): EcoViteCompatiblePlugin;
 /**
  * Injects `__eco` metadata into EcoComponent config objects in file content.
  *

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

@@ -1,7 +1,9 @@
-import path from "node:path";
-import { parseSync } from "oxc-parser";
-import { fileSystem } from "@ecopages/file-system";
+import { cachedParseSync } from "../cache/module-parse-cache.js";
 import { rapidhash } from "../utils/hash.js";
+import {
+  createEcoBuildPluginFromSourceTransform,
+  createVitePluginFromSourceTransform
+} from "./source-transform.js";
 const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
 const VALID_LOADER_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
 function hasValidLoaderExtension(ext) {
@@ -16,7 +18,13 @@ function buildExtensionToIntegrationMap(integrations) {
   const mapping = [];
   for (const integration of integrations) {
     for (const ext of integration.extensions) {
-      mapping.push([ext, integration.name]);
+      mapping.push([
+        ext,
+        {
+          name: integration.name,
+          jsxImportSource: integration.jsxImportSource
+        }
+      ]);
     }
   }
   mapping.sort((a, b) => b[0].length - a[0].length);
@@ -28,7 +36,14 @@ function detectIntegration(filePath, extensionToIntegration) {
       return integration;
     }
   }
-  return "ghtml";
+  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) {
@@ -38,30 +53,31 @@ function createExtensionPattern(extensions) {
   const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, "\\$&"));
   return new RegExp(`(${escaped.join("|")})(\\?.*)?$`);
 }
-function createEcoComponentMetaPlugin(options) {
+function createEcoComponentMetaTransform(options) {
+  const allExtensions = options.config.integrations.flatMap((integration) => integration.extensions).filter(hasValidLoaderExtension);
+  if (allExtensions.length === 0) {
+    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
+  }
+  const extensionPattern = createExtensionPattern(allExtensions);
+  const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
   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"
-        };
-      });
+    enforce: "pre",
+    filter: extensionPattern,
+    transform(code, id) {
+      const integration = detectIntegration(id, extensionToIntegration);
+      return {
+        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
+      };
     }
   };
 }
+function createEcoComponentMetaPlugin(options) {
+  return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
+}
+function createEcoComponentMetaVitePlugin(options) {
+  return createVitePluginFromSourceTransform(createEcoComponentMetaTransform(options));
+}
 function findInjectionPoints(node, insertions, injection, isInsideEcoComponent = false) {
   if (!node || typeof node !== "object") return;
   const n = node;
@@ -129,7 +145,7 @@ function findInjectionPoints(node, insertions, injection, isInsideEcoComponent =
   }
 }
 function injectEcoMeta(contents, filePath, integration) {
-  const result = parseSync(filePath, contents);
+  const result = cachedParseSync(filePath, contents);
   if (result.errors.length > 0) {
     console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
     return contents;
@@ -152,6 +168,8 @@ function injectEcoMeta(contents, filePath, integration) {
 var eco_component_meta_plugin_default = createEcoComponentMetaPlugin;
 export {
   createEcoComponentMetaPlugin,
+  createEcoComponentMetaTransform,
+  createEcoComponentMetaVitePlugin,
   eco_component_meta_plugin_default as default,
   injectEcoMeta
 };

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

@@ -0,0 +1,33 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+/**
+ * Options for the shared foreign-JSX override build plugin.
+ */
+export interface ForeignJsxOverrideOptions {
+    /** JSX runtime that should own the transformed foreign files. */
+    hostJsxImportSource: string;
+    /** Extensions claimed by other JSX integrations that may appear in the host graph. */
+    foreignExtensions: string[];
+    /** More specific owned suffixes that must not be claimed by this override. */
+    excludeExtensions?: string[];
+    /** Optional plugin name override for debug output. */
+    name?: string;
+}
+/**
+ * Build plugin that prepends a `@jsxImportSource` pragma to foreign integration
+ * files bundled into a host integration's client graph.
+ *
+ * When a host integration (e.g. React) bundles a component file that belongs to
+ * another JSX integration (e.g. `.kita.tsx`), that file inherits the project
+ * `tsconfig` JSX runtime which produces the wrong output (HTML strings instead
+ * of framework elements). This plugin rewrites the source to explicitly target
+ * the host's JSX factory so the bundler compiles every JSX expression into the
+ * correct element creation calls.
+ *
+ * The plugin is intentionally framework-agnostic: any integration that does
+ * client-side bundling can use it by passing its own `jsxImportSource` and the
+ * set of foreign extensions collected from the app config.
+ *
+ * When no JSX-bearing foreign extensions are present, the returned plugin is a
+ * no-op so integrations can register it unconditionally.
+ */
+export declare function createForeignJsxOverridePlugin(options: ForeignJsxOverrideOptions): EcoBuildPlugin;

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

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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")
+  );
+  if (extensions.length === 0) {
+    return {
+      name: options.name ?? "foreign-jsx-override",
+      setup() {
+      }
+    };
+  }
+  const pragma = `/** @jsxImportSource ${options.hostJsxImportSource} */
+`;
+  const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
+  return {
+    name: options.name ?? "foreign-jsx-override",
+    setup(build) {
+      build.onLoad({ filter }, (args) => {
+        if (excludedExtensions.some((extension) => args.path.endsWith(extension))) {
+          return void 0;
+        }
+        const source = readFileSync(args.path, "utf-8");
+        const loader = args.path.endsWith(".jsx") ? "jsx" : "tsx";
+        if (source.includes("@jsxImportSource")) {
+          return void 0;
+        }
+        return {
+          contents: pragma + source,
+          loader,
+          resolveDir: path.dirname(args.path)
+        };
+      });
+    }
+  };
+}
+export {
+  createForeignJsxOverridePlugin
+};

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

@@ -1,16 +1,37 @@
-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 { EcoBuildPlugin } from '../build/build-types.js';
+import { type BrowserRuntimeManifest } from '../build/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 { 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 { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
+export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
+/**
+ * Type-erased integration plugin stored in app-level registries.
+ *
+ * Ecopages keeps one heterogeneous integration list, while each plugin and
+ * renderer still owns its framework-specific render payload type internally.
+ */
+export type AnyIntegrationPlugin = IntegrationPlugin<unknown>;
 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 declare function mergeIntegrationOptions<TDefaults, TOverrides>(defaults: TDefaults, overrides: TOverrides): TDefaults & TOverrides;
+export declare function assertIntegrationInvariant(condition: boolean, message?: string): asserts condition;
+/**
+ * Base configuration shared by all integration plugins.
+ *
+ * @remarks
+ * Integrations declare their file ownership, optional runtime requirements, and
+ * any global assets or build-time contributions here. Runtime-only side effects
+ * belong in `setup()` rather than the constructor.
+ */
 export interface IntegrationPluginConfig {
     /**
      * The name of the integration plugin.
@@ -38,30 +59,46 @@ export interface IntegrationPluginConfig {
      * app can start with this integration enabled.
      */
     runtimeCapability?: RuntimeCapabilityDeclaration;
+    /**
+     * JSX import source owned by this integration.
+     *
+     * @remarks
+     * This is primarily used by mixed-JSX flows where host-owned browser bundles
+     * need to preserve the correct JSX runtime for files claimed by the
+     * integration.
+     */
+    jsxImportSource?: string;
 }
-/**
- * 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[];
+    rendererModules?: unknown;
     runtimeOrigin: string;
 }) => IntegrationRenderer<C>;
+/**
+ * Base class for framework integrations.
+ *
+ * @remarks
+ * An integration owns three main concerns:
+ * - which file extensions it claims
+ * - which renderer class turns those files into HTML
+ * - which build-time or runtime contributions must be registered for that framework
+ *
+ * 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:
+ * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
+ * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
+ */
 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[];
     protected resolvedIntegrationDependencies: ProcessedAsset[];
     protected options?: Record<string, unknown>;
@@ -70,8 +107,42 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     protected hmrManager?: IHmrManager;
     runtimeOrigin: string;
     get plugins(): EcoBuildPlugin[];
+    /**
+     * 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(): EcoBuildPlugin[];
+    /**
+     * 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(): BrowserRuntimeManifest;
+    /**
+     * 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: IntegrationPluginConfig);
+    /**
+     * 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: EcoPagesAppConfig): void;
+    /**
+     * Records the runtime origin used for page-module loading and renderer setup.
+     */
     setRuntimeOrigin(runtimeOrigin: string): void;
     /**
      * Returns an HMR strategy for this integration, if applicable.
@@ -83,48 +154,63 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * ```typescript
      * getHmrStrategy(): HmrStrategy {
      *   const context = this.hmrManager!.getDefaultContext();
-     *   return new ReactHmrStrategy(context);
+     *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeManifest });
      * }
      * ```
      */
     getHmrStrategy?(): HmrStrategy | undefined;
     /**
-     * Returns bare-specifier mappings that should be registered in the active
-     * runtime specifier registry.
+     * Attaches the shared HMR manager and registers integration-owned development hooks.
      *
      * @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.
+     * 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.
      */
-    getRuntimeSpecifierMap(): Record<string, string>;
     setHmrManager(hmrManager: IHmrManager): void;
+    /**
+     * Creates the asset-processing service used for global integration dependencies.
+     */
     initializeAssetDefinitionService(): void;
+    /**
+     * Returns processed global assets resolved during `setup()`.
+     */
     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.
+     * Creates the shared renderer options owned by core lifecycle setup.
+     */
+    protected createRendererOptions(options?: {
+        rendererModules?: unknown;
+    }): {
+        appConfig: EcoPagesAppConfig;
+        assetProcessingService: AssetProcessingService;
+        resolvedIntegrationDependencies: ProcessedAsset[];
+        rendererModules: unknown;
+        runtimeOrigin: string;
+    };
+    /**
+     * Attaches runtime-only services after a renderer instance has been created.
+     */
+    protected attachRendererRuntimeServices<T extends IntegrationRenderer<C>>(renderer: T): T;
+    /**
+     * Instantiates the integration renderer with app-owned services.
      *
-     * @param input Boundary metadata for the current render pass.
-     * @returns `true` when the boundary should be deferred; otherwise `false`.
+     * @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;
      */
-    shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): IntegrationRenderer<C>;
     /**
      * 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()`.
+     * Integrations can override this when runtime or build plugin declarations must
+     * be materialized ahead of runtime startup. Runtime-only side effects stay in
+     * `setup()`.
      */
     prepareBuildContributions(): Promise<void>;
     /**
@@ -132,5 +218,13 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * sealed manifest contributions.
      */
     setup(): Promise<void>;
+    /**
+     * 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.
+     */
     teardown(): Promise<void>;
 }