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

package/src/react-hmr-strategy.ts

@@ -8,18 +8,19 @@
  */
 
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { HmrStrategy, HmrStrategyType, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
-import { defaultBuildAdapter } from '@ecopages/core/build/build-adapter';
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import { createRuntimeSpecifierAliasPlugin } from '@ecopages/core/build/runtime-specifier-alias-plugin';
 import { FileNotFoundError, fileSystem } from '@ecopages/file-system';
 import { Logger } from '@ecopages/logger';
-import type { DefaultHmrContext, EcoComponentConfig } from '@ecopages/core';
+import type { DefaultHmrContext } from '@ecopages/core';
 import type { CompileOptions } from '@mdx-js/mdx';
 import { injectHmrHandler } from './utils/hmr-scripts.ts';
 import { createClientGraphBoundaryPlugin } from './utils/client-graph-boundary-plugin.ts';
 import { collectPageDeclaredModules, collectPageDeclaredModulesFromModule } from './utils/declared-modules.ts';
+import { getReactClientGraphAllowSpecifiers } from './utils/react-runtime-specifier-map.ts';
+import { createUseSyncExternalStoreShimPlugin } from './utils/use-sync-external-store-shim-plugin.ts';
 import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.ts';
 
 const appLogger = new Logger('[ReactHmrStrategy]');
@@ -33,9 +34,11 @@ const appLogger = new Logger('[ReactHmrStrategy]');
  * The processing steps are:
  * 1. Check if any React entrypoints are registered
  * 2. Rebuild all React entrypoints (the changed file could be a dependency)
- * 3. Replace bare specifiers with runtime URLs
- * 4. Inject HMR acceptance handler
- * 5. Broadcast update events for each rebuilt entrypoint
+ * 3. Rebuild browser output through the shared browser bundle service while
+ *    preserving React-specific runtime aliases and graph policy
+ * 4. Read page config metadata through the shared server-module loading path
+ * 5. Inject HMR acceptance handler
+ * 6. Broadcast update events for each rebuilt entrypoint
  *
  * @remarks
  * This strategy has higher priority than generic JsHmrStrategy, allowing it
@@ -63,84 +66,13 @@ const appLogger = new Logger('[ReactHmrStrategy]');
 export class ReactHmrStrategy extends HmrStrategy {
 	readonly type = HmrStrategyType.INTEGRATION;
 	private mdxCompilerOptions?: CompileOptions;
-	private readonly knownEntrypoints = new Set<string>();
-
+	private readonly ownedTemplateExtensions: Set<string>;
+	private readonly allTemplateExtensions: string[];
 	private async importNodePageModule(entrypointPath: string): Promise<{
-		default?: { config?: EcoComponentConfig };
-		config?: EcoComponentConfig;
+		default?: { config?: Record<string, unknown> };
+		config?: Record<string, unknown>;
 	}> {
-		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)) as {
-			default?: { config?: EcoComponentConfig };
-			config?: EcoComponentConfig;
-		};
-	}
-
-	private createUseSyncExternalStoreShimPlugin(): EcoBuildPlugin {
-		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',
-					}),
-				);
-			},
-		};
+		return await this.context.importServerModule(entrypointPath);
 	}
 
 	/**
@@ -156,14 +88,25 @@ export 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.
 	 */
+	private context: DefaultHmrContext;
+	private pageMetadataCache: ReactHmrPageMetadataCache;
+	private explicitGraphEnabled: boolean;
+
 	constructor(
-		private context: DefaultHmrContext,
-		private pageMetadataCache: ReactHmrPageMetadataCache,
+		context: DefaultHmrContext,
+		pageMetadataCache: ReactHmrPageMetadataCache,
 		mdxCompilerOptions?: CompileOptions,
-		private explicitGraphEnabled = false,
+		ownedTemplateExtensions: string[] = ['.tsx'],
+		allTemplateExtensions: string[] = ['.tsx'],
+		explicitGraphEnabled = false,
 	) {
 		super();
+		this.context = context;
+		this.pageMetadataCache = pageMetadataCache;
+		this.explicitGraphEnabled = explicitGraphEnabled;
 		this.mdxCompilerOptions = mdxCompilerOptions;
+		this.ownedTemplateExtensions = new Set(ownedTemplateExtensions);
+		this.allTemplateExtensions = [...allTemplateExtensions].sort((a, b) => b.length - a.length);
 	}
 
 	/**
@@ -173,15 +116,11 @@ export class ReactHmrStrategy extends HmrStrategy {
 	 * (including `node:*`) from breaking the browser bundle.
 	 */
 	private getBuildPlugins(declaredModules?: string[]): EcoBuildPlugin[] {
-		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({
@@ -189,17 +128,50 @@ export class ReactHmrStrategy extends HmrStrategy {
 				alwaysAllowSpecifiers: allowSpecifiers,
 				declaredModules,
 			}),
+			...(runtimeAliasPlugin ? [runtimeAliasPlugin] : []),
 			...this.context.getPlugins(),
-			this.createUseSyncExternalStoreShimPlugin(),
+			createUseSyncExternalStoreShimPlugin({
+				name: 'react-hmr-use-sync-external-store-shim',
+				namespace: 'ecopages-react-hmr-shim',
+			}),
 		];
 	}
 
 	private isReactEntrypoint(filePath: string): boolean {
-		if (filePath.endsWith('.tsx')) {
+		if (filePath.endsWith('.mdx')) {
+			return this.mdxCompilerOptions !== undefined;
+		}
+
+		if (!filePath.endsWith('.tsx')) {
+			return false;
+		}
+
+		if (!this.isRouteTemplate(filePath)) {
 			return true;
 		}
 
-		return filePath.endsWith('.mdx') && this.mdxCompilerOptions !== undefined;
+		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.
+	 */
+	private isRouteTemplate(filePath: string): boolean {
+		return filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+	}
+
+	private resolveTemplateExtension(filePath: string): string | undefined {
+		return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
 	}
 
 	/**
@@ -258,11 +230,10 @@ export class ReactHmrStrategy extends HmrStrategy {
 			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: string[] = [];
 		for (const [entrypoint, outputUrl] of entrypointsToBuild) {
@@ -335,16 +306,13 @@ export class ReactHmrStrategy extends HmrStrategy {
 				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'],
 			});
 
 			if (!result.success) {
@@ -375,7 +343,7 @@ export class ReactHmrStrategy extends HmrStrategy {
 	}
 
 	/**
-	 * 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
@@ -392,7 +360,6 @@ export class ReactHmrStrategy extends HmrStrategy {
 		try {
 			let code = await fileSystem.readFile(tempPath);
 
-			code = this.replaceBareSpecifiers(code);
 			code = injectHmrHandler(code);
 
 			await fileSystem.writeAsync(finalPath, code);
@@ -416,29 +383,4 @@ export 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
-	 */
-	private replaceBareSpecifiers(code: string): string {
-		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;
-	}
 }

package/src/react-renderer.d.ts

@@ -12,6 +12,11 @@ import { ReactBundleService } from './services/react-bundle.service.js';
 import { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
 import { ReactPageModuleService } from './services/react-page-module.service.js';
 import { ReactHydrationAssetService } from './services/react-hydration-asset.service.js';
+type ReactPageModule = EcoPageFile<{
+    config?: EcoComponentConfig;
+}> & {
+    config?: EcoComponentConfig;
+};
 /**
  * Error thrown when an error occurs while rendering a React component.
  */
@@ -32,7 +37,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 +61,101 @@ 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;
+    /**
+     * 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.
      *
      * This preserves DOM shape for global CSS/layout selectors while keeping a
      * deterministic mount target per component instance.
@@ -82,25 +173,53 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
      * @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;
-    }>>;
+    /**
+     * 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.
+     */
+    protected importPageFile(file: string): Promise<ReactPageModule>;
+    /**
+     * 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>;
 }
+export {};