@ecopages/core 0.2.0-alpha.37 → 0.2.0-alpha.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.37",
+  "version": "0.2.0-alpha.39",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.37",
+    "@ecopages/file-system": "0.2.0-alpha.39",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

package/src/eco/eco.browser.js

@@ -10,6 +10,10 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function embed(component2, props, children) {
+  const nextProps = children === void 0 ? props : { ...props, children };
+  return component2(nextProps);
+}
 function html(options) {
   return createComponentFactory(options);
 }
@@ -71,6 +75,7 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  embed,
   html,
   layout,
   page,

package/src/eco/eco.js

@@ -46,6 +46,26 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function isMissingForeignChildInterceptionError(error) {
+  return error instanceof Error && error.message.startsWith("[ecopages] Missing foreign-child interception from ");
+}
+function embed(component2, props, children) {
+  const activeRenderContext = getComponentRenderContext();
+  const ecoComponent = component2;
+  const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
+  const componentFile = ecoComponent.config?.__eco?.file ?? "unknown component";
+  const nextProps = children === void 0 ? props : { ...props, children };
+  try {
+    return component2(nextProps);
+  } catch (error) {
+    if (!isMissingForeignChildInterceptionError(error)) {
+      throw error;
+    }
+    throw new Error(
+      `[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? "unknown integration"} to ${targetIntegration ?? "unknown integration"} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`
+    );
+  }
+}
 function html(options) {
   return createComponentFactory(options);
 }
@@ -86,6 +106,7 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  embed,
   html,
   layout,
   page,

package/src/eco/eco.types.d.ts

@@ -4,6 +4,51 @@
  */
 import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
+/**
+ * Extracts the props type from one eco component.
+ */
+export type PropsOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<infer P, any> ? P : never;
+/**
+ * Extracts the render result type from one eco component.
+ */
+export type ResultOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<any, infer R> ? R : never;
+/**
+ * Narrows an eco component to its callable function signature.
+ *
+ * This is useful for helper modules such as `EcoEmbed` that invoke a component
+ * directly and need to exclude the non-callable metadata shape from the public
+ * type surface.
+ */
+export type CallableComponentOf<TComponent extends EcoComponent> = Extract<TComponent, (props: any, ...args: any[]) => any>;
+/**
+ * Extracts the declared `children` type from one eco component when present.
+ */
+export type ChildrenOf<TComponent extends EcoComponent> = PropsOf<TComponent> extends {
+    children?: infer T;
+} ? T : PropsOf<TComponent> extends {
+    children: infer T;
+} ? T : never;
+/**
+ * Extracts the props accepted by `eco.embed()` before optional `children`
+ * injection.
+ *
+ * When the target component already declares `children`, callers pass the rest
+ * of the props bag here and provide `children` as the third `eco.embed()`
+ * argument or the `EcoEmbed` wrapper children slot.
+ */
+export type EmbedPropsOf<TComponent extends EcoComponent> = 'children' extends keyof PropsOf<TComponent> ? Omit<PropsOf<TComponent>, 'children'> : PropsOf<TComponent>;
+/**
+ * Props accepted by integration-owned `EcoEmbed` adapters.
+ *
+ * The `component` field is narrowed to the callable portion of the target eco
+ * component so JSX wrappers can invoke `eco.embed()` without repeating local
+ * callable-component extraction logic.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = {
+    component: CallableComponentOf<TComponent>;
+    props: EmbedPropsOf<TComponent>;
+    children?: unknown;
+};
 type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
     [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
 };
@@ -139,6 +184,16 @@ export interface Eco {
      * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
      */
     component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+    /**
+     * Render a component explicitly, with an optional `children` argument.
+     *
+     * This is useful when authoring crosses integration boundaries and inline JSX
+     * would otherwise force one file to model multiple JSX namespaces.
+     */
+    embed: {
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: PropsOf<TComponent>): ResultOf<TComponent>;
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: EmbedPropsOf<TComponent>, children: ChildrenOf<TComponent> | unknown): ResultOf<TComponent>;
+    };
     /**
      * Create a document shell component for the HTML wrapper.
      */

package/src/services/assets/asset-processing-service/processors/script/node-module-script.processor.d.ts

@@ -1,7 +1,42 @@
 import type { NodeModuleScriptAsset } from '../../assets.types.js';
 import { BaseScriptProcessor } from '../base/base-script-processor.js';
+/**
+ * Processes browser script assets whose entrypoint is referenced by package specifier.
+ *
+ * @remarks
+ * Resolution stays app-boundary-first: prefer the active build adapter, then fall back
+ * to ESM export-map resolution, and only then probe a small set of literal file paths.
+ */
 export declare class NodeModuleScriptProcessor extends BaseScriptProcessor<NodeModuleScriptAsset> {
     process(dep: NodeModuleScriptAsset): Promise<import("../../assets.types.js").ProcessedAsset>;
+    /**
+     * Resolves a node-module script entry from the current app boundary.
+     *
+     * @remarks
+     * The build adapter remains the primary resolution surface because Bun/native
+     * host-owned builds may have a more accurate view of aliases and package
+     * ownership than core does. The local fallback only runs when that adapter
+     * resolution is unavailable.
+     */
     private resolveModulePath;
+    /**
+     * Resolves browser-owned script specifiers without relying on CommonJS resolution.
+     *
+     * @remarks
+     * This path intentionally stays ESM-first because these assets are emitted as
+     * browser scripts. We first ask Node's ESM resolver to evaluate the package
+     * export map from the app boundary. If that still fails, we fall back to a
+     * bounded filesystem probe so direct file installs and package subpaths like
+     * `pkg/client/entry` still resolve when the export map does not cover them.
+     */
     private resolveModulePathFallback;
+    /**
+     * Returns the file candidates we accept during the final literal filesystem probe.
+     *
+     * @remarks
+     * This is intentionally small and browser-entry-oriented: direct files, common
+     * JS extensions, and `index.*` entrypoints. If a package needs anything more
+     * exotic, it should resolve through the adapter or ESM export-map path above.
+     */
+    private getFallbackCandidatePaths;
 }

package/src/services/assets/asset-processing-service/processors/script/node-module-script.processor.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
 import { getAppBuildAdapter } from "../../../../../build/build-adapter.js";
 import { BaseScriptProcessor } from "../base/base-script-processor.js";
@@ -46,6 +47,15 @@ class NodeModuleScriptProcessor extends BaseScriptProcessor {
       };
     });
   }
+  /**
+   * Resolves a node-module script entry from the current app boundary.
+   *
+   * @remarks
+   * The build adapter remains the primary resolution surface because Bun/native
+   * host-owned builds may have a more accurate view of aliases and package
+   * ownership than core does. The local fallback only runs when that adapter
+   * resolution is unavailable.
+   */
   resolveModulePath(importPath, rootDir) {
     if (path.isAbsolute(importPath) && fileSystem.exists(importPath)) {
       return importPath;
@@ -56,13 +66,28 @@ class NodeModuleScriptProcessor extends BaseScriptProcessor {
       return this.resolveModulePathFallback(importPath, rootDir);
     }
   }
+  /**
+   * Resolves browser-owned script specifiers without relying on CommonJS resolution.
+   *
+   * @remarks
+   * This path intentionally stays ESM-first because these assets are emitted as
+   * browser scripts. We first ask Node's ESM resolver to evaluate the package
+   * export map from the app boundary. If that still fails, we fall back to a
+   * bounded filesystem probe so direct file installs and package subpaths like
+   * `pkg/client/entry` still resolve when the export map does not cover them.
+   */
   resolveModulePathFallback(importPath, rootDir, maxDepth = 5) {
+    try {
+      return fileURLToPath(import.meta.resolve(importPath, pathToFileURL(path.join(rootDir, "package.json")).href));
+    } catch {
+    }
     let currentDir = rootDir;
     let remainingDepth = maxDepth;
     while (remainingDepth >= 0) {
-      const modulePath = path.join(currentDir, "node_modules", importPath);
-      if (fileSystem.exists(modulePath)) {
-        return modulePath;
+      for (const candidatePath of this.getFallbackCandidatePaths(currentDir, importPath)) {
+        if (fileSystem.exists(candidatePath)) {
+          return candidatePath;
+        }
       }
       const parentDir = path.dirname(currentDir);
       if (parentDir === currentDir) {
@@ -73,6 +98,26 @@ class NodeModuleScriptProcessor extends BaseScriptProcessor {
     }
     throw new Error(`Could not resolve module '${importPath}' from '${rootDir}'`);
   }
+  /**
+   * Returns the file candidates we accept during the final literal filesystem probe.
+   *
+   * @remarks
+   * This is intentionally small and browser-entry-oriented: direct files, common
+   * JS extensions, and `index.*` entrypoints. If a package needs anything more
+   * exotic, it should resolve through the adapter or ESM export-map path above.
+   */
+  getFallbackCandidatePaths(rootDir, importPath) {
+    const moduleBasePath = path.join(rootDir, "node_modules", importPath);
+    return [
+      moduleBasePath,
+      `${moduleBasePath}.js`,
+      `${moduleBasePath}.mjs`,
+      `${moduleBasePath}.cjs`,
+      path.join(moduleBasePath, "index.js"),
+      path.join(moduleBasePath, "index.mjs"),
+      path.join(moduleBasePath, "index.cjs")
+    ];
+  }
 }
 export {
   NodeModuleScriptProcessor