@ecopages/core 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/public-types.js';
 import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
 /**
  * A renderer for the ghtml integration.
@@ -10,6 +10,11 @@ import { IntegrationRenderer, type RenderToResponseContext } from '../../route-r
  */
 export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("../../index.browser.js").ComponentBoundaryRuntime;
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }

package/src/integrations/ghtml/ghtml-renderer.js

@@ -4,6 +4,18 @@ import {
 import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentBoundaryWithQueuedForeignBoundaries(
+      input,
+      input.component
+    );
+  }
+  createComponentBoundaryRuntime(options) {
+    return this.createQueuedBoundaryRuntime({
+      boundaryInput: options.boundaryInput,
+      rendererCache: options.rendererCache
+    });
+  }
   async render({
     params,
     query,
@@ -16,42 +28,31 @@ class GhtmlRenderer extends IntegrationRenderer {
     HtmlTemplate
   }) {
     try {
-      const pageContent = await Page({ params, query, ...props, locals: pageLocals });
-      const children = Layout && typeof Layout === "function" ? await Layout({ children: pageContent, locals }) : pageContent;
-      const body = await HtmlTemplate({
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
         metadata,
-        children,
-        pageProps: props || {}
+        pageProps: props ?? {}
       });
-      return this.DOC_TYPE + body;
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
     }
   }
   async renderToResponse(view, props, ctx) {
     try {
-      const Layout = view.config?.layout;
-      const viewFn = view;
-      const pageContent = await viewFn(props);
-      let body;
-      if (ctx.partial) {
-        body = pageContent;
-      } else {
-        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-        const HtmlTemplate = await this.getHtmlTemplate();
-        const metadata = view.metadata ? await view.metadata({
-          params: {},
-          query: {},
-          props,
-          appConfig: this.appConfig
-        }) : this.appConfig.defaultMetadata;
-        body = this.DOC_TYPE + await HtmlTemplate({
-          metadata,
-          children,
-          pageProps: props
-        });
-      }
-      return this.createHtmlResponse(body, ctx);
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: view.config?.layout
+      });
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

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

@@ -0,0 +1,31 @@
+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[];
+    /** 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 esbuild 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,35 @@
+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"));
+  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) => {
+        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,7 +1,7 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
-import type { EcoComponent, EcoPagesElement } from '../types/public-types.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';
@@ -11,6 +11,14 @@ 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";
 };
+/**
+ * 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,19 +46,16 @@ 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;
@@ -58,6 +63,19 @@ type RendererClass<C> = new (options: {
     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.
+ */
 export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
     readonly name: string;
     readonly extensions: string[];
@@ -73,8 +91,33 @@ 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[];
+    /**
+     * 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.
@@ -96,8 +139,8 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * 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.
+     * Integrations that own browser runtime bundles can override this to expose
+     * stable bare specifiers for client-side imports.
      *
      * Today these mappings are consumed by the development runtime and browser
      * bundle aliasing path. They are intentionally generic enough to grow into a
@@ -105,31 +148,41 @@ export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
      * map contents into core.
      */
     getRuntimeSpecifierMap(): Record<string, string>;
+    /**
+     * Attaches the shared HMR manager and registers integration-owned development hooks.
+     *
+     * @remarks
+     * The default implementation registers both runtime bare-specifier mappings and
+     * the optional integration HMR strategy. Integrations should override this only
+     * when they need to extend that shared behavior rather than replace it.
+     */
     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(options?: {
-        rendererModules?: unknown;
-    }): IntegrationRenderer<C>;
     /**
-     * Declares whether a component boundary targeting this integration should be
-     * deferred through the marker pipeline.
+     * Instantiates the integration renderer with app-owned services.
      *
-     * 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`.
+     * @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.
      */
-    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>;
     /**
@@ -137,5 +190,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>;
 }

package/src/plugins/integration-plugin.js

@@ -18,6 +18,24 @@ class IntegrationPlugin {
   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 [];
+  }
+  /**
+   * 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;
@@ -26,10 +44,19 @@ class IntegrationPlugin {
     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;
   }
@@ -38,8 +65,8 @@ class IntegrationPlugin {
    * 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.
+   * Integrations that own browser runtime bundles can override this to expose
+   * stable bare specifiers for client-side imports.
    *
    * Today these mappings are consumed by the development runtime and browser
    * bundle aliasing path. They are intentionally generic enough to grow into a
@@ -49,6 +76,14 @@ class IntegrationPlugin {
   getRuntimeSpecifierMap() {
     return {};
   }
+  /**
+   * Attaches the shared HMR manager and registers integration-owned development hooks.
+   *
+   * @remarks
+   * The default implementation registers both runtime bare-specifier mappings and
+   * 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;
     hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
@@ -60,6 +95,9 @@ class IntegrationPlugin {
       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);
@@ -67,9 +105,20 @@ class IntegrationPlugin {
       this.assetProcessingService.setHmrManager(this.hmrManager);
     }
   }
+  /**
+   * Returns processed global assets resolved during `setup()`.
+   */
   getResolvedIntegrationDependencies() {
     return this.resolvedIntegrationDependencies;
   }
+  /**
+   * 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.
+   */
   initializeRenderer(options) {
     if (!this.appConfig) {
       throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
@@ -91,27 +140,13 @@ class IntegrationPlugin {
     }
     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()`.
+   * 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() {
   }
@@ -128,6 +163,14 @@ class IntegrationPlugin {
     );
     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() {
   }
 }