@ecopages/react 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/react-hmr-strategy.js

@@ -1,14 +1,22 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import { HmrStrategy, HmrStrategyType } from "@ecopages/core/hmr/hmr-strategy";
-import { defaultBuildAdapter } from "@ecopages/core/build/build-adapter";
+import { createRuntimeSpecifierAliasPlugin } from "@ecopages/core/build/runtime-specifier-alias-plugin";
 import { FileNotFoundError, fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
 import { injectHmrHandler } from "./utils/hmr-scripts.js";
 import { createClientGraphBoundaryPlugin } from "./utils/client-graph-boundary-plugin.js";
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from "./utils/declared-modules.js";
+import { getReactClientGraphAllowSpecifiers } from "./utils/react-runtime-specifier-map.js";
+import { createUseSyncExternalStoreShimPlugin } from "./utils/use-sync-external-store-shim-plugin.js";
 const appLogger = new Logger("[ReactHmrStrategy]");
 class ReactHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.INTEGRATION;
+  mdxCompilerOptions;
+  ownedTemplateExtensions;
+  allTemplateExtensions;
+  async importNodePageModule(entrypointPath) {
+    return await this.context.importServerModule(entrypointPath);
+  }
   /**
    * Creates a new React HMR strategy instance.
    *
@@ -22,75 +30,17 @@ class ReactHmrStrategy extends HmrStrategy {
    * @param explicitGraphEnabled - Enables explicit graph mode for React HMR bundling.
    * In explicit mode, HMR builds omit AST server-only stripping plugins in React paths.
    */
-  constructor(context, pageMetadataCache, mdxCompilerOptions, explicitGraphEnabled = false) {
+  context;
+  pageMetadataCache;
+  explicitGraphEnabled;
+  constructor(context, pageMetadataCache, mdxCompilerOptions, ownedTemplateExtensions = [".tsx"], allTemplateExtensions = [".tsx"], explicitGraphEnabled = false) {
     super();
     this.context = context;
     this.pageMetadataCache = pageMetadataCache;
     this.explicitGraphEnabled = explicitGraphEnabled;
     this.mdxCompilerOptions = mdxCompilerOptions;
-  }
-  type = HmrStrategyType.INTEGRATION;
-  mdxCompilerOptions;
-  knownEntrypoints = /* @__PURE__ */ new Set();
-  async importNodePageModule(entrypointPath) {
-    const srcDir = this.context.getSrcDir();
-    const rootDir = path.dirname(srcDir);
-    const outdir = path.join(path.resolve(this.context.getDistDir(), "..", ".."), ".server-modules");
-    const fileBaseName = path.basename(entrypointPath, path.extname(entrypointPath));
-    const fileHash = fileSystem.hash(entrypointPath);
-    const outputFileName = `${fileBaseName}-${fileHash}.js`;
-    const buildResult = await defaultBuildAdapter.build({
-      entrypoints: [entrypointPath],
-      root: rootDir,
-      outdir,
-      target: "node",
-      format: "esm",
-      sourcemap: "none",
-      splitting: false,
-      minify: false,
-      naming: outputFileName
-    });
-    if (!buildResult.success) {
-      const details = buildResult.logs.map((log) => log.message).join(" | ");
-      throw new Error(`Error transpiling React HMR page module: ${details}`);
-    }
-    const preferredOutputPath = path.join(outdir, outputFileName);
-    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => output.path.endsWith(".js"))?.path;
-    if (!compiledOutput) {
-      throw new Error(`No transpiled output generated for React HMR page module: ${entrypointPath}`);
-    }
-    return await import(pathToFileURL(compiledOutput).href);
-  }
-  createUseSyncExternalStoreShimPlugin() {
-    return {
-      name: "react-hmr-use-sync-external-store-shim",
-      setup(build) {
-        build.onResolve({ filter: /^use-sync-external-store\/shim(?:\/index\.js)?$/ }, () => ({
-          path: "use-sync-external-store/shim",
-          namespace: "ecopages-react-hmr-shim"
-        }));
-        build.onLoad(
-          { filter: /^use-sync-external-store\/shim$/, namespace: "ecopages-react-hmr-shim" },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-        build.onLoad({ filter: /[\\/]use-sync-external-store[\\/]shim[\\/]index\.js$/ }, () => ({
-          contents: "export { useSyncExternalStore } from 'react';",
-          loader: "js"
-        }));
-        build.onLoad(
-          {
-            filter: /[\\/]use-sync-external-store[\\/]cjs[\\/]use-sync-external-store-shim\.development\.js$/
-          },
-          () => ({
-            contents: "export { useSyncExternalStore } from 'react';",
-            loader: "js"
-          })
-        );
-      }
-    };
+    this.ownedTemplateExtensions = new Set(ownedTemplateExtensions);
+    this.allTemplateExtensions = [...allTemplateExtensions].sort((a, b) => b.length - a.length);
   }
   /**
    * Returns build plugins for React HMR bundling.
@@ -99,30 +49,53 @@ class ReactHmrStrategy extends HmrStrategy {
    * (including `node:*`) from breaking the browser bundle.
    */
   getBuildPlugins(declaredModules) {
-    const allowSpecifiers = [
-      "@ecopages/core",
-      "react",
-      "react-dom",
-      "react/jsx-runtime",
-      "react/jsx-dev-runtime",
-      "react-dom/client",
-      ...Array.from(this.context.getSpecifierMap().keys())
-    ];
+    const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.context.getSpecifierMap().keys());
+    const runtimeAliasPlugin = createRuntimeSpecifierAliasPlugin(this.context.getSpecifierMap(), {
+      name: "react-hmr-runtime-specifier-alias"
+    });
     return [
       createClientGraphBoundaryPlugin({
         absWorkingDir: path.dirname(this.context.getSrcDir()),
         alwaysAllowSpecifiers: allowSpecifiers,
         declaredModules
       }),
+      ...runtimeAliasPlugin ? [runtimeAliasPlugin] : [],
       ...this.context.getPlugins(),
-      this.createUseSyncExternalStoreShimPlugin()
+      createUseSyncExternalStoreShimPlugin({
+        name: "react-hmr-use-sync-external-store-shim",
+        namespace: "ecopages-react-hmr-shim"
+      })
     ];
   }
   isReactEntrypoint(filePath) {
-    if (filePath.endsWith(".tsx")) {
+    if (filePath.endsWith(".mdx")) {
+      return this.mdxCompilerOptions !== void 0;
+    }
+    if (!filePath.endsWith(".tsx")) {
+      return false;
+    }
+    if (!this.isRouteTemplate(filePath)) {
       return true;
     }
-    return filePath.endsWith(".mdx") && this.mdxCompilerOptions !== void 0;
+    const templateExtension = this.resolveTemplateExtension(filePath);
+    if (!templateExtension) {
+      return false;
+    }
+    return this.ownedTemplateExtensions.has(templateExtension);
+  }
+  /**
+   * Returns true when a route file uses a compound extension like `page.foo.tsx`.
+   *
+   * @remarks
+   * React integration owns plain `.tsx` route templates. Compound extensions in
+   * pages/layouts are integration-specific route templates and should not be
+   * claimed by React HMR strategy.
+   */
+  isRouteTemplate(filePath) {
+    return filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+  }
+  resolveTemplateExtension(filePath) {
+    return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
   }
   /**
    * Determines if the file is a React/MDX entrypoint that's registered for HMR.
@@ -174,8 +147,8 @@ class ReactHmrStrategy extends HmrStrategy {
     if (isLayout) {
       appLogger.debug(`Detected layout file change: ${_filePath}`);
     }
-    const entrypointsToBuild = !this.knownEntrypoints.has(_filePath) && watchedFiles.has(_filePath) ? [[_filePath, watchedFiles.get(_filePath)]] : watchedFiles.entries();
-    this.knownEntrypoints.add(_filePath);
+    const changedEntrypointOutput = watchedFiles.get(_filePath);
+    const entrypointsToBuild = changedEntrypointOutput ? [[_filePath, changedEntrypointOutput]] : watchedFiles.entries();
     const updates = [];
     for (const [entrypoint, outputUrl] of entrypointsToBuild) {
       if (!this.isReactEntrypoint(entrypoint)) {
@@ -235,16 +208,13 @@ class ReactHmrStrategy extends HmrStrategy {
         const mdxPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
         plugins.unshift(mdxPlugin);
       }
-      const result = await defaultBuildAdapter.build({
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
         entrypoints: [entrypointPath],
         outdir: tempDir,
         naming: `[name].[hash].tmp`,
-        target: "browser",
-        format: "esm",
-        sourcemap: "none",
         plugins,
-        minify: false,
-        external: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"]
+        minify: false
       });
       if (!result.success) {
         appLogger.error(`Failed to build ${entrypointPath}:`, result.logs);
@@ -255,13 +225,33 @@ class ReactHmrStrategy extends HmrStrategy {
         appLogger.error(`No output file generated for ${entrypointPath}`);
         return false;
       }
-      const processed = await this.processOutput(tempFile, outputPath, outputUrl);
+      const resolvedTempFile = await this.resolveTempOutputPath(tempFile);
+      if (!resolvedTempFile) {
+        appLogger.debug(`Skipping stale temp output for ${outputUrl}: ${tempFile}`);
+        return false;
+      }
+      const processed = await this.processOutput(resolvedTempFile, outputPath, outputUrl);
       return processed;
     } catch (error) {
       appLogger.error(`Error bundling ${entrypointPath}:`, error);
       return false;
     }
   }
+  async resolveTempOutputPath(tempPath) {
+    if (fileSystem.exists(tempPath)) {
+      return tempPath;
+    }
+    if (!tempPath.includes("[hash]")) {
+      return tempPath;
+    }
+    const directory = path.dirname(tempPath);
+    const pattern = path.basename(tempPath).replaceAll("[hash]", "*");
+    const matches = await fileSystem.glob([pattern], { cwd: directory });
+    if (matches.length === 0) {
+      return null;
+    }
+    return path.isAbsolute(matches[0]) ? matches[0] : path.join(directory, matches[0]);
+  }
   /**
    * Encodes dynamic route segments (brackets) in file paths.
    * Converts `[slug]` to `_slug_` to avoid filesystem issues.
@@ -270,7 +260,7 @@ class ReactHmrStrategy extends HmrStrategy {
     return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
   }
   /**
-   * Processes bundled output by replacing specifiers and injecting HMR handler.
+   * Processes bundled output and injects the React HMR handler.
    * Writes to temp file first, then renames atomically to avoid conflicts.
    *
    * @param tempPath - Path to the temporary bundled file
@@ -285,7 +275,6 @@ class ReactHmrStrategy extends HmrStrategy {
     }
     try {
       let code = await fileSystem.readFile(tempPath);
-      code = this.replaceBareSpecifiers(code);
       code = injectHmrHandler(code);
       await fileSystem.writeAsync(finalPath, code);
       await fileSystem.removeAsync(tempPath).catch(() => {
@@ -305,27 +294,6 @@ class ReactHmrStrategy extends HmrStrategy {
       return false;
     }
   }
-  /**
-   * Replaces bare specifiers with runtime URLs.
-   *
-   * Handles both static imports and dynamic imports.
-   *
-   * @param code - The bundled code to transform
-   * @returns The transformed code with runtime URLs
-   */
-  replaceBareSpecifiers(code) {
-    const specifierMap = this.context.getSpecifierMap();
-    if (specifierMap.size === 0) {
-      return code;
-    }
-    let result = code;
-    for (const [bareSpec, runtimeUrl] of specifierMap.entries()) {
-      const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, "g"), `from "${runtimeUrl}"`);
-      result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, "g"), `import("${runtimeUrl}")`);
-    }
-    return result;
-  }
 }
 export {
   ReactHmrStrategy

package/src/react-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the React renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoComponentConfig, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
 import { type ReactNode } from 'react';
@@ -32,7 +32,6 @@ export declare class BundleError extends Error {
 export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
     name: string;
     componentDirectory: string;
-    private componentRenderSequence;
     static routerAdapter: ReactRouterAdapter | undefined;
     static mdxCompilerOptions: CompileOptions | undefined;
     static mdxExtensions: string[];
@@ -57,14 +56,117 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
         runtimeOrigin: string;
     });
     protected shouldRenderPageComponent(): boolean;
+    /**
+     * 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.
+     */
+    private getComponentIntegration;
+    /**
+     * 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.
+     */
+    private isReactManagedComponent;
+    /**
+     * 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.
+     */
+    private buildRouterPageDataScript;
+    private getRouterDocumentAttributes;
+    /**
+     * 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.
+     */
+    private asReactComponent;
+    /**
+     * 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.
+     */
+    private asNonReactShellComponent;
+    /**
+     * 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.
+     */
+    private buildSerializedPageProps;
+    /**
+     * Appends route hydration assets for a concrete page/view file to the current
+     * HTML transformer state.
+     */
+    private appendHydrationAssetsForFile;
+    /**
+     * 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.
+     */
+    private resolveViewMetadata;
+    /**
+     * 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.
+     */
+    private renderNonReactShellComponent;
+    /**
+     * Renders one React component boundary for marker-graph orchestration.
+     *
+     * When the marker resolver has already stitched child HTML for this boundary,
+     * the child payload must remain raw SSR output rather than a React string
+     * child, otherwise React would escape it. This helper renders a unique token
+     * through React and swaps that token back to the stitched HTML afterward.
+     *
+     * @param input Component render input reconstructed from marker metadata.
+     * @param context React-specific render context for stable token generation.
+     * @returns Serialized component HTML with stitched child markup preserved.
+     */
+    private renderComponentHtml;
+    private buildHydrationProps;
+    /**
+     * 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.
+     */
+    private composePageContent;
+    /**
+     * 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.
+     */
+    private renderDocument;
     /**
      * 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.
+     * - When stitched child HTML is provided, that boundary is treated as a pure SSR
+     *   composition step and does not emit hydration assets for the parent wrapper.
      *
      * This preserves DOM shape for global CSS/layout selectors while keeping a
      * deterministic mount target per component instance.
@@ -76,31 +178,52 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * @returns True if the file is an MDX file
      */
     isMdxFile(filePath: string): boolean;
+    protected usesIntegrationPageImporter(file: string): boolean;
+    protected importIntegrationPageFile(file: string): Promise<EcoPageFile>;
+    protected normalizeImportedPageFile<TPageModule extends EcoPageFile>(file: string, pageModule: TPageModule): TPageModule;
     /**
      * Processes MDX-specific configuration dependencies including layout dependencies.
      * @param pagePath - Absolute path to the MDX page file
      * @returns Processed assets for MDX configuration dependencies
      */
     private processMdxConfigDependencies;
+    private processDeclaredMdxSsrLazyDependencies;
+    private collectDeclaredMdxSsrLazyDependencies;
     buildRouteRenderAssets(pagePath: string): Promise<ProcessedAsset[]>;
-    protected importPageFile(file: string): Promise<EcoPageFile<{
-        config?: EcoComponentConfig;
-    }>>;
+    /**
+     * 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.
+     */
     render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
+    protected getDocumentAttributes(): Record<string, string> | undefined;
     /**
-     * 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
      */
     private getSerializableLocals;
+    /**
+     * 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.
+     */
     renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
 }