@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/index.d.ts

@@ -1,5 +1,6 @@
-export type * from './public-types.js';
+export type * from './types/public-types.js';
 export type * from './eco/eco.types.js';
 export { eco } from './eco/eco.js';
-export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';
+export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';

package/src/index.js

@@ -1,10 +1,21 @@
 import { eco } from "./eco/eco.js";
-import { EcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "./define-api-handler.js";
+import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
+import {
+  createEcoBuildPluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
+  getAppSourceTransforms,
+  createVitePluginFromSourceTransform,
+  normalizeTransformId
+} from "./plugins/source-transform.js";
+import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
 export {
-  EcopagesApp,
-  createApp,
+  createEcoBuildPluginFromSourceTransform,
+  createEcoComponentMetaTransform,
+  createVitePluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
   defineApiHandler,
   defineGroupHandler,
-  eco
+  eco,
+  getAppSourceTransforms,
+  normalizeTransformId
 };

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

@@ -2,14 +2,15 @@
  * This module contains the ghtml renderer
  * @module
  */
-import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../public-types.js';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/integration-renderer.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.
  * It renders a page using the HtmlTemplate and Page components.
  */
 export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
     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

@@ -1,7 +1,15 @@
-import { IntegrationRenderer } from "../../route-renderer/integration-renderer.js";
-import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
+import {
+  IntegrationRenderer
+} from "../../route-renderer/orchestration/integration-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlRenderer extends IntegrationRenderer {
   name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentWithQueuedForeignSubtrees(
+      input,
+      input.component
+    );
+  }
   async render({
     params,
     query,
@@ -14,42 +22,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/integrations/ghtml/ghtml.constants.d.ts

@@ -0,0 +1 @@
+export declare const GHTML_PLUGIN_NAME = "ghtml";

package/src/integrations/ghtml/ghtml.constants.js

@@ -0,0 +1,4 @@
+const GHTML_PLUGIN_NAME = "ghtml";
+export {
+  GHTML_PLUGIN_NAME
+};

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -1,9 +1,5 @@
-import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
-import { GhtmlRenderer } from './ghtml-renderer';
-/**
- * The name of the ghtml plugin
- */
-export declare const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
+import { GhtmlRenderer } from './ghtml-renderer.js';
 /**
  * The Ghtml plugin class
  * This plugin provides support for ghtml components in Ecopages

package/src/integrations/ghtml/ghtml.plugin.js

@@ -1,6 +1,6 @@
-import { IntegrationPlugin } from "../../plugins/integration-plugin";
-import { GhtmlRenderer } from "./ghtml-renderer";
-const GHTML_PLUGIN_NAME = "ghtml";
+import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { GhtmlRenderer } from "./ghtml-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
 class GhtmlPlugin extends IntegrationPlugin {
   renderer = GhtmlRenderer;
   constructor(options) {
@@ -15,7 +15,6 @@ function ghtmlPlugin(options) {
   return new GhtmlPlugin(options);
 }
 export {
-  GHTML_PLUGIN_NAME,
   GhtmlPlugin,
   ghtmlPlugin
 };

package/src/plugins/README.md

@@ -0,0 +1,35 @@
+# Plugin Contracts
+
+This directory contains the authoring contracts for Ecopages integrations, processors, and related plugin-facing runtime declarations.
+
+## Purpose
+
+The plugin layer defines what packages are allowed to declare about themselves, while core retains orchestration ownership.
+
+These contracts are responsible for:
+
+- integration registration and lifecycle hooks
+- processor registration and asset capability declaration
+- runtime capability declaration and validation input
+- shared build-plugin bridge types used by integrations and processors
+
+## Main Files
+
+- `integration-plugin.ts`: framework-semantics contract for render integrations
+- `processor.ts`: asset-transformation contract for processors
+- `runtime-capability.ts`: runtime compatibility declaration types
+- `source-transform.ts`: bundler-neutral source-transform primitive with Ecopages adapters plus app-level Vite plugin composition helpers
+- `eco-component-meta-plugin.ts`: shared metadata transform used by core loading/build paths
+
+## Ownership Rules
+
+- Integrations own rendering semantics, hydration behavior, and integration-specific HMR strategy.
+- Processors own asset semantics, cache ownership, and processor-specific watch behavior.
+- Core owns lifecycle ordering, startup orchestration, and manifest assembly.
+
+## Lifecycle Summary
+
+1. Config build validates and prepares plugin contributions.
+2. Core seals the app-owned build manifest.
+3. Runtime startup calls runtime-only setup hooks.
+4. Request-time rendering and development invalidation reuse those finalized contracts.

package/src/plugins/alias-resolver-plugin.d.ts

@@ -1,2 +1,3 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
+export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
 export declare function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin;

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

@@ -1,9 +1,11 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
 function findResolvablePath(candidate) {
   if (path.extname(candidate)) {
-    return existsSync(candidate) ? candidate : void 0;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
   }
   for (const extension of RESOLVABLE_EXTENSIONS) {
     const fileCandidate = `${candidate}${extension}`;
@@ -19,13 +21,32 @@ function findResolvablePath(candidate) {
   }
   return void 0;
 }
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+  return target ?? resolvedPath;
+}
+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) {
   return {
     name: "ecopages-alias-resolver",
     setup(build) {
       build.onResolve({ filter: /^@\// }, (args) => {
-        const candidate = path.join(srcDir, args.path.slice(2));
-        const resolved = findResolvablePath(candidate);
+        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
         if (resolved) {
           return { path: resolved };
         }
@@ -35,5 +56,6 @@ function createAliasResolverPlugin(srcDir) {
   };
 }
 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.
  *
@@ -47,6 +53,8 @@ export interface EcoComponentDirPluginOptions {
  * Supported patterns:
  * - `eco.page({ ... })` - Page component declarations
  * - `eco.component({ ... })` - Reusable component declarations
+ * - `eco.html({ ... })` - HTML shell declarations
+ * - `eco.layout({ ... })` - Layout declarations
  * - `Component.config = { ... }` - Config assignment pattern
  * - `config: { ... }` - Config property in object literals
  * - `export const config = { ... }` - Exported config declarations
@@ -63,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 { 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;
@@ -70,7 +86,7 @@ function findInjectionPoints(node, insertions, injection, isInsideEcoComponent =
     if (callee?.type === "MemberExpression" || callee?.type === "StaticMemberExpression") {
       const obj = callee.object;
       const prop = callee.property;
-      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component")) {
+      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component" || prop?.name === "html" || prop?.name === "layout")) {
         const args = n.arguments;
         const firstArg = args?.[0];
         if (firstArg?.type === "ObjectExpression") {
@@ -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 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,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
+};