@ecopages/kitajs 0.2.0-alpha.9 → 0.2.0-beta.1

package/README.md

@@ -1,13 +1,15 @@
 # @ecopages/kitajs
 
-Integration plugin for [KitaJS](https://kitajs.org/html/) HTML within the Ecopages framework. It enables the rendering of standard JSX templates for multi-page applications.
+Integration plugin for [KitaJS](https://kitajs.org/html/) HTML in Ecopages. Use it when Kita should own `.kita.tsx` routes, page shells, and document shells in HTML-first apps.
 
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/kitajs
+bun add @ecopages/kitajs @kitajs/html @kitajs/ts-html-plugin
 ```
 
+`@kitajs/html` and `@kitajs/ts-html-plugin` are required peer dependencies for this package.
+
 ## Usage
 
 Import and register the `kitajsPlugin` in your `eco.config.ts`.
@@ -23,3 +25,19 @@ const config = await new ConfigBuilder()
 
 export default config;
 ```
+
+## What This Integration Owns
+
+- `.kita.tsx` route files.
+- Page, layout, and document shells rendered by `@kitajs/html`.
+- HTML-first outer shells that host nested foreign subtrees from other integrations.
+
+## Mixed Rendering
+
+Kita works well as the outer renderer in mixed apps. When a Kita-owned page encounters a nested foreign child from another integration, Ecopages resolves that foreign subtree with its owning renderer and inserts the resulting HTML back into the Kita shell.
+
+Important:
+
+- Components that may render foreign children must declare those children in `config.dependencies.components`.
+- Ecopages validates mixed-renderer ownership from declared dependencies during render preparation instead of inferring every foreign child from rendered HTML.
+- Kita remains an HTML-first outer shell. Same-integration Kita children do not go through a separate universal child serialization contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/kitajs",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.0-beta.1",
   "description": "Kitajs plugin for Ecopages",
   "keywords": [
     "ecopages",
@@ -11,13 +11,27 @@
   "main": "./src/kitajs.plugin.js",
   "types": "./src/kitajs.plugin.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/kitajs.plugin.js",
+      "types": "./src/kitajs.plugin.d.ts"
+    },
+    "./eco-embed": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    },
+    "./eco-embed.ts": {
+      "default": "./src/eco-embed.js",
+      "types": "./src/eco-embed.d.ts"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/ecopages/ecopages.git",
     "directory": "packages/integrations/kitajs"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.9",
+    "@ecopages/core": "0.2.0-beta.1",
     "@kitajs/html": "^4.1.0",
     "@kitajs/ts-html-plugin": "^4.0.1"
   }

package/src/eco-embed.d.ts

@@ -0,0 +1,10 @@
+import type { EcoComponent, EcoEmbedProps as CoreEcoEmbedProps, EcoPagesElement } from '@ecopages/core';
+/**
+ * Props for the Kita-owned `EcoEmbed` adapter.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = CoreEcoEmbedProps<TComponent>;
+/**
+ * Renders a foreign or same-integration eco component from a Kita JSX file
+ * without forcing inline mixed-JSX authoring.
+ */
+export declare function EcoEmbed<TComponent extends EcoComponent>({ component, props, children, }: EcoEmbedProps<TComponent>): EcoPagesElement;

package/src/eco-embed.js

@@ -0,0 +1,11 @@
+import { eco } from "@ecopages/core";
+function EcoEmbed({
+  component,
+  props,
+  children
+}) {
+  return eco.embed(component, props, children);
+}
+export {
+  EcoEmbed
+};

package/src/kitajs-renderer.d.ts

@@ -10,8 +10,9 @@ import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/cor
  */
 export declare class KitaRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    private isFunctionComponent;
     /**
-     * Renders a Kita component boundary for component-level orchestration.
+     * Renders a Kita-owned foreign subtree for component-level orchestration.
      *
      * Includes component-scoped dependency assets when declared.
      */

package/src/kitajs-renderer.js

@@ -1,27 +1,20 @@
 import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
-import { PLUGIN_NAME } from "./kitajs.plugin.js";
+import { KITAJS_PLUGIN_NAME } from "./kitajs.constants.js";
 class KitaRenderer extends IntegrationRenderer {
-  name = PLUGIN_NAME;
+  name = KITAJS_PLUGIN_NAME;
+  isFunctionComponent(component) {
+    return typeof component === "function";
+  }
   /**
-   * Renders a Kita component boundary for component-level orchestration.
+   * Renders a Kita-owned foreign subtree for component-level orchestration.
    *
    * Includes component-scoped dependency assets when declared.
    */
   async renderComponent(input) {
-    const component = input.component;
-    const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
-    const content = await component(props);
-    const html = String(content);
-    const hasDependencies = Boolean(input.component.config?.dependencies);
-    const canResolveAssets = typeof this.assetProcessingService?.processDependencies === "function";
-    const assets = hasDependencies && canResolveAssets ? await this.processComponentDependencies([input.component]) : void 0;
-    return {
-      html,
-      canAttachAttributes: true,
-      rootTag: this.getRootTagName(html),
-      integrationName: this.name,
-      assets
-    };
+    if (!this.isFunctionComponent(input.component)) {
+      throw new TypeError("Kita renderer expected a callable component.");
+    }
+    return this.renderStringComponentWithQueuedForeignSubtrees(input, input.component);
   }
   async render({
     params,
@@ -35,52 +28,31 @@ class KitaRenderer 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,
-        pageProps: props ?? {},
-        children
+        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 HtmlTemplate = ctx.partial ? void 0 : await this.getHtmlTemplate();
-      const metadata = ctx.partial || !HtmlTemplate ? void 0 : view.metadata ? await view.metadata({
-        params: {},
-        query: {},
+      return await this.renderViewWithDocumentShell({
+        view,
         props,
-        appConfig: this.appConfig
-      }) : this.appConfig.defaultMetadata;
-      if (!ctx.partial) {
-        await this.prepareViewDependencies(view, Layout);
-      }
-      const viewFn = view;
-      const renderExecution = await this.captureHtmlRender(async () => {
-        const pageContent = await viewFn(props);
-        if (ctx.partial) {
-          return pageContent;
-        }
-        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-        return this.DOC_TYPE + await HtmlTemplate({
-          metadata: metadata ?? this.appConfig.defaultMetadata,
-          pageProps: props ?? {},
-          children: children ?? ""
-        });
-      });
-      const componentsToResolve = ctx.partial ? [view] : [HtmlTemplate, Layout, view].filter(Boolean);
-      const body = await this.finalizeCapturedHtmlRender({
-        html: renderExecution.html,
-        componentsToResolve,
-        graphContext: renderExecution.graphContext,
-        partial: ctx.partial
+        ctx,
+        layout: view.config?.layout
       });
-      return this.createHtmlResponse(body, ctx);
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

package/src/kitajs.constants.d.ts

@@ -0,0 +1 @@
+export declare const KITAJS_PLUGIN_NAME = "kitajs";

package/src/kitajs.constants.js

@@ -0,0 +1,4 @@
+const KITAJS_PLUGIN_NAME = "kitajs";
+export {
+  KITAJS_PLUGIN_NAME
+};

package/src/kitajs.plugin.js

@@ -1,12 +1,14 @@
 import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
 import { KitaRenderer } from "./kitajs-renderer.js";
-const PLUGIN_NAME = "kitajs";
+import { KITAJS_PLUGIN_NAME } from "./kitajs.constants.js";
+const PLUGIN_NAME = KITAJS_PLUGIN_NAME;
 class KitaHtmlPlugin extends IntegrationPlugin {
   renderer = KitaRenderer;
   constructor(options) {
     super({
       name: PLUGIN_NAME,
       extensions: [".kita.tsx"],
+      jsxImportSource: "@kitajs/html",
       ...options
     });
   }

package/CHANGELOG.md

@@ -1,23 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/kitajs` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Bug Fixes
-
-- Fixed explicit `ctx.render()` flows so deferred cross-integration layout components resolve through the marker pipeline instead of crashing during direct server rendering.
-
-### Features
-
-- Aligned KitaJS with the unified orchestration pipeline.
-
-### Refactoring
-
-- Tightened Kita component typing and cleaned up ambient module declarations.
-
-### Tests
-
-- Updated integration coverage for the orchestration pipeline and Node and esbuild compatibility.

package/src/kitajs-renderer.ts

@@ -1,141 +0,0 @@
-/**
- * This module contains the Kita.js renderer
- * @module
- */
-
-import type {
-	ComponentRenderInput,
-	ComponentRenderResult,
-	EcoComponent,
-	EcoPagesElement,
-	IntegrationRendererRenderOptions,
-	RouteRendererBody,
-} from '@ecopages/core';
-import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
-import { PLUGIN_NAME } from './kitajs.plugin.ts';
-
-/** Narrows an EcoComponent to its KitaJS callable signature. */
-type KitaViewFn<P> = (props: P) => Promise<EcoPagesElement> | EcoPagesElement;
-
-/** KitaJS layout function signature. */
-type KitaLayoutFn = (props: { children: EcoPagesElement } & Record<string, unknown>) => Promise<EcoPagesElement>;
-
-/**
- * A renderer for the Kita.js integration.
- * It renders a page using the HtmlTemplate and Page components.
- */
-export class KitaRenderer extends IntegrationRenderer<EcoPagesElement> {
-	name = PLUGIN_NAME;
-
-	/**
-	 * Renders a Kita component boundary for component-level orchestration.
-	 *
-	 * Includes component-scoped dependency assets when declared.
-	 */
-	override async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
-		const component = input.component as KitaViewFn<Record<string, unknown>>;
-		const props = input.children === undefined ? input.props : { ...input.props, children: input.children };
-		const content = await component(props);
-		const html = String(content);
-		const hasDependencies = Boolean(input.component.config?.dependencies);
-		const canResolveAssets = typeof this.assetProcessingService?.processDependencies === 'function';
-		const assets =
-			hasDependencies && canResolveAssets
-				? await this.processComponentDependencies([input.component])
-				: undefined;
-
-		return {
-			html,
-			canAttachAttributes: true,
-			rootTag: this.getRootTagName(html),
-			integrationName: this.name,
-			assets,
-		};
-	}
-
-	async render({
-		params,
-		query,
-		props,
-		locals,
-		pageLocals,
-		metadata,
-		Page,
-		Layout,
-		HtmlTemplate,
-	}: IntegrationRendererRenderOptions): Promise<RouteRendererBody> {
-		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({
-				metadata,
-				pageProps: props ?? {},
-				children,
-			});
-
-			return this.DOC_TYPE + body;
-		} catch (error) {
-			throw this.createRenderError('Error rendering page', error);
-		}
-	}
-
-	async renderToResponse<P = Record<string, unknown>>(
-		view: EcoComponent<P>,
-		props: P,
-		ctx: RenderToResponseContext,
-	): Promise<Response> {
-		try {
-			const Layout = view.config?.layout as KitaLayoutFn | undefined;
-			const HtmlTemplate = ctx.partial ? undefined : await this.getHtmlTemplate();
-			const metadata =
-				ctx.partial || !HtmlTemplate
-					? undefined
-					: view.metadata
-						? await view.metadata({
-								params: {},
-								query: {},
-								props: props as Record<string, unknown>,
-								appConfig: this.appConfig,
-							})
-						: this.appConfig.defaultMetadata;
-
-			if (!ctx.partial) {
-				await this.prepareViewDependencies(view, Layout as EcoComponent | undefined);
-			}
-
-			const viewFn = view as KitaViewFn<P>;
-			const renderExecution = await this.captureHtmlRender(async () => {
-				const pageContent = await viewFn(props);
-
-				if (ctx.partial) {
-					return pageContent;
-				}
-
-				const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-				return (
-					this.DOC_TYPE +
-					(await HtmlTemplate!({
-						metadata: metadata ?? this.appConfig.defaultMetadata,
-						pageProps: (props as Record<string, unknown>) ?? {},
-						children: children ?? '',
-					}))
-				);
-			});
-
-			const componentsToResolve = ctx.partial
-				? [view]
-				: ([HtmlTemplate, Layout, view].filter(Boolean) as EcoComponent[]);
-			const body = await this.finalizeCapturedHtmlRender({
-				html: renderExecution.html,
-				componentsToResolve,
-				graphContext: renderExecution.graphContext,
-				partial: ctx.partial,
-			});
-
-			return this.createHtmlResponse(body, ctx);
-		} catch (error) {
-			throw this.createRenderError('Error rendering view', error);
-		}
-	}
-}

package/src/kitajs.plugin.ts

@@ -1,32 +0,0 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
-import { KitaRenderer } from './kitajs-renderer.ts';
-
-/**
- * The name of the Kita.js plugin
- */
-export const PLUGIN_NAME = 'kitajs';
-
-/**
- * The Kita.js plugin class
- * This plugin provides support for Kita.js components in Ecopages
- */
-export class KitaHtmlPlugin extends IntegrationPlugin {
-	renderer = KitaRenderer;
-
-	constructor(options?: Omit<IntegrationPluginConfig, 'name'>) {
-		super({
-			name: PLUGIN_NAME,
-			extensions: ['.kita.tsx'],
-			...options,
-		});
-	}
-}
-
-/**
- * Factory function to create a Kita.js plugin instance.
- * @param options Configuration options for the Kita.js plugin
- * @returns A new KitaHtmlPlugin instance
- */
-export function kitajsPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): KitaHtmlPlugin {
-	return new KitaHtmlPlugin(options);
-}