@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/react-renderer.js

@@ -1,7 +1,11 @@
 import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
 import { LocalsAccessError } from "@ecopages/core/errors/locals-access-error";
 import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
+import { getAppBuildExecutor } from "@ecopages/core/build/build-adapter";
 import { rapidhash } from "@ecopages/core/hash";
+import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
+import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from "@ecopages/core/router/navigation-coordinator";
+import path from "node:path";
 import { createElement } from "react";
 import { renderToReadableStream, renderToString } from "react-dom/server";
 import { PLUGIN_NAME } from "./react.plugin.js";
@@ -17,16 +21,16 @@ class ReactRenderError extends Error {
   }
 }
 class BundleError extends Error {
+  logs;
   constructor(message, logs) {
     super(message);
-    this.logs = logs;
     this.name = "BundleError";
+    this.logs = logs;
   }
 }
 class ReactRenderer extends IntegrationRenderer {
   name = PLUGIN_NAME;
   componentDirectory = RESOLVED_ASSETS_DIR;
-  componentRenderSequence = 0;
   static routerAdapter;
   static mdxCompilerOptions;
   static mdxExtensions = [".mdx"];
@@ -54,6 +58,8 @@ class ReactRenderer extends IntegrationRenderer {
     this.pageModuleService = new ReactPageModuleService({
       rootDir: this.appConfig.rootDir,
       distDir: this.appConfig.absolutePaths.distDir,
+      workDir: this.appConfig.absolutePaths.workDir,
+      buildExecutor: getAppBuildExecutor(this.appConfig),
       layoutsDir: this.appConfig.absolutePaths.layoutsDir,
       componentsDir: this.appConfig.absolutePaths.componentsDir,
       mdxCompilerOptions: ReactRenderer.mdxCompilerOptions,
@@ -72,20 +78,199 @@ class ReactRenderer extends IntegrationRenderer {
   shouldRenderPageComponent() {
     return false;
   }
+  /**
+   * Reads the declared integration name for a component or layout.
+   *
+   * We honor both the explicit `config.integration` override and injected
+   * `config.__eco.integration` metadata because pages can arrive here through
+   * authored config as well as build-time component metadata.
+   */
+  getComponentIntegration(component) {
+    return component?.config?.integration ?? component?.config?.__eco?.integration;
+  }
+  /**
+   * Returns whether a component should stay inside the React render lane.
+   *
+   * Components without explicit integration metadata are treated as React-owned
+   * here because this renderer only receives them after the route pipeline has
+   * already selected the React integration.
+   */
+  isReactManagedComponent(component) {
+    const integration = this.getComponentIntegration(component);
+    return integration === void 0 || integration === this.name;
+  }
+  /**
+   * Creates the canonical page-props payload used by router hydration.
+   *
+   * React pages embedded in a non-React HTML shell still need to expose the same
+   * page-data contract as fully React-owned documents so navigation and hydration
+   * can read one marker consistently.
+   */
+  buildRouterPageDataScript(pageProps) {
+    const safeJson = JSON.stringify(pageProps || {}).replace(/</g, "\\u003c");
+    return `<script id="__ECO_PAGE_DATA__" type="application/json">${safeJson}<\/script>`;
+  }
+  getRouterDocumentAttributes() {
+    if (!ReactRenderer.routerAdapter) {
+      return void 0;
+    }
+    return {
+      [ECO_DOCUMENT_OWNER_ATTRIBUTE]: "react-router"
+    };
+  }
+  /**
+   * Commits a framework-agnostic component to React semantics.
+   *
+   * This is one of the two real cast boundaries in this file. Core keeps
+   * `EcoComponent` broad so integrations can share the same public surface; once
+   * the React renderer is executing, `createElement()` needs a concrete React
+   * component signature.
+   */
+  asReactComponent(component) {
+    return component;
+  }
+  /**
+   * Commits a mixed-shell component to the string-returning contract required by
+   * non-React layouts and HTML templates.
+   *
+   * This is the second real cast boundary: once we decide a shell is not managed
+   * by React, we call it directly and require serialized HTML back.
+   */
+  asNonReactShellComponent(component) {
+    return component;
+  }
+  /**
+   * Builds the serialized page-props payload embedded into the final HTML.
+   *
+   * The document payload is intentionally narrower than the full server render
+   * input: only routing data, public page props, and explicitly allowed locals are
+   * exposed to the browser.
+   */
+  buildSerializedPageProps(options) {
+    return {
+      ...options.pageProps,
+      params: options.params,
+      query: options.query,
+      ...options.safeLocals && { locals: options.safeLocals }
+    };
+  }
+  /**
+   * Appends route hydration assets for a concrete page/view file to the current
+   * HTML transformer state.
+   */
+  async appendHydrationAssetsForFile(filePath) {
+    if (!filePath) {
+      return;
+    }
+    const hydrationAssets = await this.buildRouteRenderAssets(filePath);
+    this.htmlTransformer.setProcessedDependencies([
+      ...this.htmlTransformer.getProcessedDependencies(),
+      ...hydrationAssets
+    ]);
+  }
+  /**
+   * Resolves metadata for direct `renderToResponse()` calls.
+   *
+   * View rendering bypasses the normal route-file pipeline, so metadata has to be
+   * evaluated here from either the component-level generator or the application
+   * default.
+   */
+  async resolveViewMetadata(view, props) {
+    return view.metadata ? await view.metadata({
+      params: {},
+      query: {},
+      props,
+      appConfig: this.appConfig
+    }) : this.appConfig.defaultMetadata;
+  }
+  /**
+   * Renders a non-React layout or HTML template and enforces that mixed shells
+   * return serialized HTML.
+   *
+   * The React renderer can compose through another integration's shell, but only
+   * if that shell yields a string that can be inserted into the final document.
+   */
+  async renderNonReactShellComponent(Component, props, label) {
+    const output = await Component(props);
+    if (typeof output === "string") {
+      return output;
+    }
+    throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
+  }
+  /**
+   * Produces the page body before the final HTML template is applied.
+   *
+   * This method owns the React/non-React layout split. React-managed layouts stay
+   * as React elements so they can stream normally; non-React layouts are rendered
+   * to HTML first and then passed through as serialized content.
+   */
+  async composePageContent(options) {
+    const pageElement = createElement(options.Page, options.pageProps);
+    const pageHtml = renderToString(pageElement);
+    const layoutProps = options.locals ? { locals: options.locals } : {};
+    if (!options.Layout) {
+      return { contentNode: pageElement, contentHtml: pageHtml };
+    }
+    if (this.isReactManagedComponent(options.Layout)) {
+      const layoutElement = createElement(this.asReactComponent(options.Layout), layoutProps, pageElement);
+      return {
+        contentNode: layoutElement,
+        contentHtml: renderToString(layoutElement)
+      };
+    }
+    const layoutHtml = await this.renderNonReactShellComponent(
+      this.asNonReactShellComponent(options.Layout),
+      { ...layoutProps, children: pageHtml },
+      "Layout"
+    );
+    return { contentNode: layoutHtml, contentHtml: layoutHtml };
+  }
+  /**
+   * Wraps composed page content in the final document template.
+   *
+   * React-owned HTML templates stream directly. Non-React templates receive
+   * pre-rendered page HTML plus the canonical React page-data payload so the
+   * client runtime can recover page data after cross-integration handoff.
+   */
+  async renderDocument(options) {
+    if (this.isReactManagedComponent(options.HtmlTemplate)) {
+      return renderToReadableStream(
+        createElement(
+          this.asReactComponent(options.HtmlTemplate),
+          {
+            metadata: options.metadata,
+            pageProps: options.pageProps
+          },
+          options.contentNode
+        )
+      );
+    }
+    const headContent = ReactRenderer.routerAdapter ? this.buildRouterPageDataScript(options.pageProps) : void 0;
+    return this.renderNonReactShellComponent(
+      this.asNonReactShellComponent(options.HtmlTemplate),
+      {
+        metadata: options.metadata,
+        pageProps: options.pageProps,
+        children: options.contentHtml,
+        headContent
+      },
+      "HtmlTemplate"
+    );
+  }
   /**
    * Renders a React component for component-level orchestration.
    *
    * Behavior:
    * - SSR always returns the component's own root HTML (no synthetic wrapper).
-   * - For single-root output, a stable `data-eco-component-id` attribute is attached
-   *   to the root element so the client island runtime can target it directly.
-   * - Island client scripts are emitted through `assets` and mounted independently.
+   * - When an explicit component instance id is provided, a stable
+   *   `data-eco-component-id` attribute is attached so island hydration can target it.
+   * - Without an explicit instance id, component renders remain plain SSR output.
    *
    * This preserves DOM shape for global CSS/layout selectors while keeping a
    * deterministic mount target per component instance.
    */
   async renderComponent(input) {
-    const Component = input.component;
+    const Component = this.asReactComponent(input.component);
     const componentConfig = input.component.config;
     const element = input.children === void 0 ? createElement(Component, input.props) : createElement(Component, input.props, input.children);
     let html = renderToString(element);
@@ -95,15 +280,18 @@ class ReactRenderer extends IntegrationRenderer {
     const context = input.integrationContext ?? {};
     let rootAttributes;
     let assets;
-    if (canAttachAttributes && componentFile && this.assetProcessingService) {
-      const componentInstanceId = context.componentInstanceId ?? `eco-component-${rapidhash(componentFile)}-${++this.componentRenderSequence}`;
+    if (canAttachAttributes && componentFile && context.componentInstanceId && this.assetProcessingService) {
+      const componentInstanceId = context.componentInstanceId;
       assets = await this.hydrationAssetService.buildComponentRenderAssets(
         componentFile,
         componentInstanceId,
         input.props,
         componentConfig
       );
-      rootAttributes = { "data-eco-component-id": componentInstanceId };
+      rootAttributes = {
+        "data-eco-component-id": componentInstanceId,
+        "data-eco-props": btoa(JSON.stringify(input.props ?? {}))
+      };
     }
     return {
       html,
@@ -142,7 +330,86 @@ class ReactRenderer extends IntegrationRenderer {
       };
       components.push({ config: configWithMeta });
     }
-    return this.processComponentDependencies(components);
+    const processedDependencies = await this.processComponentDependencies(components);
+    const eagerSsrLazyDependencies = await this.processDeclaredMdxSsrLazyDependencies(components, pagePath);
+    return [...processedDependencies, ...eagerSsrLazyDependencies];
+  }
+  async processDeclaredMdxSsrLazyDependencies(components, pagePath) {
+    if (!this.assetProcessingService?.processDependencies) {
+      return [];
+    }
+    const dependencies = this.collectDeclaredMdxSsrLazyDependencies(components);
+    if (dependencies.length === 0) {
+      return [];
+    }
+    return this.assetProcessingService.processDependencies(dependencies, `react-mdx-ssr-lazy:${pagePath}`);
+  }
+  collectDeclaredMdxSsrLazyDependencies(components) {
+    const dependencies = [];
+    const visitedConfigs = /* @__PURE__ */ new Set();
+    const seenKeys = /* @__PURE__ */ new Set();
+    const normalizeAttributes = (attributes) => ({
+      type: "module",
+      defer: "",
+      ...attributes ?? {}
+    });
+    const collect = (config) => {
+      if (!config || visitedConfigs.has(config)) {
+        return;
+      }
+      visitedConfigs.add(config);
+      const componentFile = config.__eco?.file;
+      if (componentFile) {
+        const componentDir = path.dirname(componentFile);
+        for (const script of config.dependencies?.scripts ?? []) {
+          if (typeof script === "string" || !script.lazy || script.ssr !== true) {
+            continue;
+          }
+          const attributes = normalizeAttributes(script.attributes);
+          if (script.content) {
+            const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
+            if (seenKeys.has(key2)) {
+              continue;
+            }
+            seenKeys.add(key2);
+            dependencies.push(
+              AssetFactory.createContentScript({
+                position: "head",
+                content: script.content,
+                attributes
+              })
+            );
+            continue;
+          }
+          if (!script.src) {
+            continue;
+          }
+          const resolvedPath = path.resolve(componentDir, script.src);
+          const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+          if (seenKeys.has(key)) {
+            continue;
+          }
+          seenKeys.add(key);
+          dependencies.push(
+            AssetFactory.createFileScript({
+              filepath: resolvedPath,
+              position: "head",
+              attributes
+            })
+          );
+        }
+      }
+      if (config.layout?.config) {
+        collect(config.layout.config);
+      }
+      for (const nestedComponent of config.dependencies?.components ?? []) {
+        collect(nestedComponent?.config);
+      }
+    };
+    for (const component of components) {
+      collect(component.config);
+    }
+    return dependencies;
   }
   async buildRouteRenderAssets(pagePath) {
     try {
@@ -172,6 +439,14 @@ class ReactRenderer extends IntegrationRenderer {
       );
     }
   }
+  /**
+   * Imports a page module while normalizing React MDX modules to the same shape
+   * as ordinary React page files.
+   *
+   * MDX page imports can expose `config` separately from the default export. The
+   * React renderer reattaches that config to the page component so downstream
+   * layout, dependency, and hydration logic can treat MDX and TSX pages the same.
+   */
   async importPageFile(file) {
     const module = this.pageModuleService.isMdxFile(file) ? await this.pageModuleService.importMdxPageFile(file) : await super.importPageFile(file);
     const { default: Page, getMetadata, config } = module;
@@ -184,6 +459,14 @@ class ReactRenderer extends IntegrationRenderer {
       config
     };
   }
+  /**
+   * Renders a full route response for the filesystem page pipeline.
+   *
+   * This path receives already-resolved route metadata, layout, locals, and HTML
+   * template instances from the shared renderer orchestration. Its main job is to
+   * serialize only the browser-safe page payload, compose the mixed React/non-
+   * React shell tree, and hand the result back as a document body.
+   */
   async render({
     params,
     query,
@@ -197,47 +480,63 @@ class ReactRenderer extends IntegrationRenderer {
     pageProps
   }) {
     try {
-      const pageElement = createElement(Page, { params, query, ...props, locals: pageLocals });
-      const contentElement = Layout ? createElement(Layout, { locals }, pageElement) : pageElement;
-      const safeLocals = this.getSerializableLocals(locals);
-      const allPageProps = {
-        ...pageProps,
+      const safeLocals = this.getSerializableLocals(locals, Page.requires);
+      const allPageProps = this.buildSerializedPageProps({
+        pageProps,
         params,
         query,
-        ...safeLocals && { locals: safeLocals }
-      };
-      return await renderToReadableStream(
-        createElement(
-          HtmlTemplate,
-          {
-            metadata,
-            pageProps: allPageProps
-          },
-          contentElement
-        )
-      );
+        safeLocals
+      });
+      const { contentNode, contentHtml } = await this.composePageContent({
+        Page: this.asReactComponent(Page),
+        Layout,
+        pageProps: { params, query, ...props, locals: pageLocals },
+        locals
+      });
+      return await this.renderDocument({
+        HtmlTemplate,
+        metadata,
+        pageProps: allPageProps,
+        contentNode,
+        contentHtml
+      });
     } catch (error) {
       throw this.createRenderError("Failed to render component", error);
     }
   }
+  getDocumentAttributes() {
+    return this.getRouterDocumentAttributes();
+  }
   /**
-   * Safely extracts locals for client-side hydration.
+   * Safely extracts the declared subset of locals for client-side hydration.
    *
    * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
-   * request-scoped data (e.g., session). This data needs to be serialized to the
-   * client for hydration to match the server-rendered output.
+   * request-scoped data (e.g., session). Only keys explicitly declared via
+   * `Page.requires` are serialized to the client so sensitive request-only data
+   * is not leaked into hydration payloads by default.
    *
    * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
    * to prevent accidental use. This method safely detects that case and returns
    * `undefined` instead of throwing.
    *
    * @param locals - The locals object from the render context
-   * @returns The locals object if serializable, undefined otherwise
+   * @param requiredLocals - Keys explicitly requested for client hydration
+   * @returns The filtered locals object if serializable, undefined otherwise
    */
-  getSerializableLocals(locals) {
+  getSerializableLocals(locals, requiredLocals) {
     try {
-      if (locals && Object.keys(locals).length > 0) {
-        return locals;
+      if (!locals) {
+        return void 0;
+      }
+      const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
+      if (requiredKeys.length === 0) {
+        return void 0;
+      }
+      const serializedLocals = Object.fromEntries(
+        requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
+      );
+      if (Object.keys(serializedLocals).length > 0) {
+        return serializedLocals;
       }
       return void 0;
     } catch (e) {
@@ -247,49 +546,54 @@ class ReactRenderer extends IntegrationRenderer {
       throw e;
     }
   }
+  /**
+   * Renders an arbitrary React view through the application's HTML shell.
+   *
+   * Unlike route rendering, this path starts from a single component rather than a
+   * page module discovered by the router. It still needs to resolve metadata,
+   * layout dependencies, and hydration assets so direct `ctx.render()` calls match
+   * normal page responses.
+   */
   async renderToResponse(view, props, ctx) {
     try {
       const viewConfig = view.config;
       const Layout = viewConfig?.layout;
-      const ViewComponent = view;
-      const pageElement = createElement(ViewComponent, props || {});
+      const ViewComponent = this.asReactComponent(view);
+      const normalizedProps = props ?? {};
       if (ctx.partial) {
-        const stream = await renderToReadableStream(pageElement);
+        const stream = await renderToReadableStream(createElement(ViewComponent, normalizedProps));
         return this.createHtmlResponse(stream, ctx);
       }
-      const contentElement = Layout ? createElement(Layout, {}, pageElement) : pageElement;
       const HtmlTemplate = await this.getHtmlTemplate();
-      const metadata = view.metadata ? await view.metadata({
-        params: {},
-        query: {},
-        props,
-        appConfig: this.appConfig
-      }) : this.appConfig.defaultMetadata;
+      const metadata = await this.resolveViewMetadata(view, props);
       await this.prepareViewDependencies(view, Layout);
-      const viewFilePath = viewConfig?.__eco?.file;
-      if (viewFilePath) {
-        const hydrationAssets = await this.buildRouteRenderAssets(viewFilePath);
-        this.htmlTransformer.setProcessedDependencies([
-          ...this.htmlTransformer.getProcessedDependencies(),
-          ...hydrationAssets
-        ]);
-      }
-      const streamBody = await renderToReadableStream(
-        createElement(
-          HtmlTemplate,
-          {
-            metadata,
-            pageProps: props
-          },
-          contentElement
-        )
-      );
+      await this.appendHydrationAssetsForFile(viewConfig?.__eco?.file);
+      const { contentNode, contentHtml } = await this.composePageContent({
+        Page: ViewComponent,
+        Layout,
+        pageProps: normalizedProps
+      });
+      const body = await this.renderDocument({
+        HtmlTemplate,
+        metadata,
+        pageProps: normalizedProps,
+        contentNode,
+        contentHtml
+      });
       const transformedResponse = await this.htmlTransformer.transform(
-        new Response(streamBody, {
+        new Response(body, {
           headers: { "Content-Type": "text/html" }
         })
       );
-      return this.createHtmlResponse(transformedResponse.body ?? "", ctx);
+      let transformedHtml = await transformedResponse.text();
+      const documentAttributes = this.getRouterDocumentAttributes();
+      if (documentAttributes) {
+        transformedHtml = this.htmlTransformer.applyAttributesToHtmlElement(
+          transformedHtml,
+          documentAttributes
+        );
+      }
+      return this.createHtmlResponse(transformedHtml, ctx);
     } catch (error) {
       throw this.createRenderError("Failed to render view", error);
     }