@ecopages/react 0.2.0-beta.8 → 0.2.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +179 -7
  2. package/package.json +54 -29
  3. package/src/app/client-only.js +15 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.js +31 -0
  6. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  7. package/src/bundling/bootstrap-package-paths.js +5 -0
  8. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +23 -8
  9. package/src/bundling/bundle.js +120 -0
  10. package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
  11. package/src/bundling/discover-layout-runtime-modules.js +185 -0
  12. package/src/bundling/runtime-alias-map.d.ts +13 -0
  13. package/src/bundling/runtime-alias-map.js +113 -0
  14. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +25 -4
  15. package/src/bundling/runtime-bundle.js +258 -0
  16. package/src/bundling/runtime-interop-plugin.js +34 -0
  17. package/src/bundling/runtime-mode.d.ts +9 -0
  18. package/src/bundling/runtime-mode.js +11 -0
  19. package/src/bundling/runtime-modules.d.ts +29 -0
  20. package/src/bundling/runtime-modules.js +49 -0
  21. package/src/client-graph/ast-transform.d.ts +18 -0
  22. package/src/client-graph/ast-transform.js +426 -0
  23. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +23 -13
  24. package/src/client-graph/boundary-cache.js +182 -0
  25. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
  26. package/src/client-graph/boundary-plugin.js +149 -0
  27. package/src/client-graph/component-config-traversal.js +77 -0
  28. package/src/client-graph/declared-modules.js +69 -0
  29. package/src/client-graph/module-classification.d.ts +3 -0
  30. package/src/client-graph/module-classification.js +43 -0
  31. package/src/{utils → client-graph}/reachability-analyzer.d.ts +4 -12
  32. package/src/client-graph/reachability-analyzer.js +515 -0
  33. package/src/client-graph/specifier-classification.d.ts +75 -0
  34. package/src/client-graph/specifier-classification.js +214 -0
  35. package/src/contracts/router-adapter.js +6 -0
  36. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  37. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  38. package/src/hmr/hmr-scripts.js +44 -0
  39. package/src/hmr/hmr-strategy.d.ts +74 -0
  40. package/src/hmr/hmr-strategy.js +351 -0
  41. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  42. package/src/hmr/page-metadata-cache.js +44 -0
  43. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  44. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  45. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  46. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  47. package/src/hydration/bootstrap-imports.d.ts +25 -0
  48. package/src/hydration/bootstrap-imports.js +33 -0
  49. package/src/hydration/hydration-asset.d.ts +84 -0
  50. package/src/hydration/hydration-asset.js +227 -0
  51. package/src/hydration/hydration-scripts.d.ts +104 -0
  52. package/src/hydration/hydration-scripts.js +483 -0
  53. package/src/hydration/hydration-scripts.test.browser.js +199 -0
  54. package/src/hydration/page-data-manifest.d.ts +58 -0
  55. package/src/hydration/page-data-manifest.js +97 -0
  56. package/src/hydration/page-data-reader.d.ts +31 -0
  57. package/src/hydration/page-data-reader.js +77 -0
  58. package/src/hydration/page-payload.d.ts +67 -0
  59. package/src/hydration/page-payload.js +106 -0
  60. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  61. package/src/hydration/serialize-page-data-script.js +30 -0
  62. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +6 -6
  63. package/src/mdx/mdx-config-dependency.js +110 -0
  64. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  65. package/src/mdx/mdx-loader-plugin.js +8 -0
  66. package/src/page/page-module.d.ts +46 -0
  67. package/src/page/page-module.js +74 -0
  68. package/src/plugin/react.constants.js +1 -0
  69. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +9 -3
  70. package/src/plugin/react.plugin.js +241 -0
  71. package/src/plugin/react.types.d.ts +156 -0
  72. package/src/plugin/react.types.js +1 -0
  73. package/src/render/component-ownership.d.ts +49 -0
  74. package/src/render/component-ownership.js +46 -0
  75. package/src/render/component-ssr.d.ts +113 -0
  76. package/src/render/component-ssr.js +180 -0
  77. package/src/render/eco-embed.js +9 -0
  78. package/src/render/errors.d.ts +16 -0
  79. package/src/render/errors.js +23 -0
  80. package/src/render/html-boundary.js +59 -0
  81. package/src/render/layout-compose.d.ts +66 -0
  82. package/src/render/layout-compose.js +134 -0
  83. package/src/render/react-renderer.d.ts +138 -0
  84. package/src/render/react-renderer.js +448 -0
  85. package/src/render/react-runtime.d.ts +13 -0
  86. package/src/render/react-runtime.js +26 -0
  87. package/src/render/unified-layout-composition.d.ts +53 -0
  88. package/src/render/unified-layout-composition.js +78 -0
  89. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
  90. package/src/eco-embed.js +0 -11
  91. package/src/react-hmr-strategy.d.ts +0 -230
  92. package/src/react-hmr-strategy.js +0 -657
  93. package/src/react-renderer.d.ts +0 -233
  94. package/src/react-renderer.js +0 -622
  95. package/src/react.constants.js +0 -4
  96. package/src/react.plugin.js +0 -209
  97. package/src/react.types.d.ts +0 -88
  98. package/src/react.types.js +0 -0
  99. package/src/router-adapter.js +0 -0
  100. package/src/services/pages-index.d.ts +0 -64
  101. package/src/services/pages-index.js +0 -73
  102. package/src/services/react-bundle.service.js +0 -86
  103. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  104. package/src/services/react-hydration-asset.service.d.ts +0 -84
  105. package/src/services/react-hydration-asset.service.js +0 -217
  106. package/src/services/react-mdx-config-dependency.service.js +0 -122
  107. package/src/services/react-page-module.service.d.ts +0 -88
  108. package/src/services/react-page-module.service.js +0 -166
  109. package/src/services/react-page-payload.service.d.ts +0 -46
  110. package/src/services/react-page-payload.service.js +0 -67
  111. package/src/services/react-runtime-bundle.service.js +0 -192
  112. package/src/utils/client-graph-boundary-cache.js +0 -116
  113. package/src/utils/client-graph-boundary-plugin.js +0 -552
  114. package/src/utils/client-only.js +0 -19
  115. package/src/utils/component-config-traversal.js +0 -54
  116. package/src/utils/declared-modules.js +0 -47
  117. package/src/utils/dynamic.js +0 -12
  118. package/src/utils/dynamic.test.browser.js +0 -33
  119. package/src/utils/hmr-scripts.js +0 -31
  120. package/src/utils/html-boundary.js +0 -55
  121. package/src/utils/hydration-scripts.d.ts +0 -92
  122. package/src/utils/hydration-scripts.js +0 -358
  123. package/src/utils/hydration-scripts.test.browser.js +0 -198
  124. package/src/utils/reachability-analyzer.js +0 -339
  125. package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
  126. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  127. package/src/utils/react-mdx-loader-plugin.js +0 -45
  128. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  129. package/src/utils/react-runtime-alias-map.js +0 -90
  130. /package/src/{utils → app}/client-only.d.ts +0 -0
  131. /package/src/{utils → app}/dynamic.d.ts +0 -0
  132. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  133. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  134. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  135. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  136. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  137. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  138. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  139. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  140. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  141. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  142. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Page module loading and configuration resolution service for React integration.
3
+ *
4
+ * Handles component identity resolution and module hydration analysis.
5
+ * MDX page modules load through the core {@link PageModuleImportService} path
6
+ * using the React plugin's server build contributions.
7
+ *
8
+ * @module
9
+ */
10
+ import { type EcoComponentConfig, type EcoPageFile } from '@ecopages/core';
11
+ /**
12
+ * Configuration for the PageModuleService.
13
+ */
14
+ export interface PageModuleServiceConfig {
15
+ layoutsDir?: string;
16
+ componentsDir?: string;
17
+ mdxExtensions: string[];
18
+ integrationName: string;
19
+ hasRouterAdapter: boolean;
20
+ }
21
+ /**
22
+ * Manages page module metadata resolution and hydration analysis for React pages.
23
+ */
24
+ export declare class PageModuleService {
25
+ private readonly config;
26
+ constructor(config: PageModuleServiceConfig);
27
+ /**
28
+ * Checks if the given file path corresponds to an MDX file based on configured extensions.
29
+ */
30
+ isMdxFile(filePath: string): boolean;
31
+ /**
32
+ * Ensures that an EcoComponentConfig has canonical identity attached.
33
+ */
34
+ ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
35
+ hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
36
+ shouldHydratePage(pageModule: EcoPageFile<{
37
+ config?: EcoComponentConfig;
38
+ }> & {
39
+ config?: EcoComponentConfig;
40
+ }): boolean;
41
+ collectPageDeclaredModules(pageModule: EcoPageFile<{
42
+ config?: EcoComponentConfig;
43
+ }> & {
44
+ config?: EcoComponentConfig;
45
+ }): string[];
46
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Page module loading and configuration resolution service for React integration.
3
+ *
4
+ * Handles component identity resolution and module hydration analysis.
5
+ * MDX page modules load through the core {@link PageModuleImportService} path
6
+ * using the React plugin's server build contributions.
7
+ *
8
+ * @module
9
+ */
10
+ import path from 'node:path';
11
+ import { bindComponentIdentity, getComponentIdentity } from '@ecopages/core';
12
+ import { rapidhash } from '@ecopages/core/hash';
13
+ import { fileSystem } from '@ecopages/file-system';
14
+ import { someInConfigTree } from '../client-graph/component-config-traversal.js';
15
+ import { collectPageDeclaredModulesFromModule } from '../client-graph/declared-modules.js';
16
+ /**
17
+ * Manages page module metadata resolution and hydration analysis for React pages.
18
+ */
19
+ export class PageModuleService {
20
+ config;
21
+ constructor(config) {
22
+ this.config = config;
23
+ }
24
+ /**
25
+ * Checks if the given file path corresponds to an MDX file based on configured extensions.
26
+ */
27
+ isMdxFile(filePath) {
28
+ return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
29
+ }
30
+ /**
31
+ * Ensures that an EcoComponentConfig has canonical identity attached.
32
+ */
33
+ ensureConfigFileMetadata(config, pagePath) {
34
+ const identity = getComponentIdentity(config);
35
+ if (identity?.file) {
36
+ return config;
37
+ }
38
+ const buildIdentity = (file) => ({
39
+ id: identity?.id ?? rapidhash(file).toString(36),
40
+ integration: identity?.integration ?? this.config.integrationName,
41
+ file,
42
+ });
43
+ const resolveDependencyValue = (value) => typeof value === 'string' ? value : value.src;
44
+ const dependencyPaths = [
45
+ ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
46
+ ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue),
47
+ ]
48
+ .filter((value) => Boolean(value))
49
+ .filter((value) => value.startsWith('./') || value.startsWith('../'));
50
+ const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter((value) => typeof value === 'string' && value.length > 0);
51
+ for (const dependencyPath of dependencyPaths) {
52
+ for (const candidateDir of candidateDirs) {
53
+ const resolvedDependency = path.resolve(candidateDir, dependencyPath);
54
+ if (fileSystem.exists(resolvedDependency)) {
55
+ return bindComponentIdentity(buildIdentity(path.join(candidateDir, path.basename(pagePath))), config);
56
+ }
57
+ }
58
+ }
59
+ return bindComponentIdentity(buildIdentity(pagePath), config);
60
+ }
61
+ hasModulesInConfig(config) {
62
+ return someInConfigTree(config, (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false);
63
+ }
64
+ shouldHydratePage(pageModule) {
65
+ if (this.config.hasRouterAdapter) {
66
+ return true;
67
+ }
68
+ const pageConfig = pageModule.default?.config;
69
+ return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
70
+ }
71
+ collectPageDeclaredModules(pageModule) {
72
+ return collectPageDeclaredModulesFromModule(pageModule);
73
+ }
74
+ }
@@ -0,0 +1 @@
1
+ export const REACT_PLUGIN_NAME = 'react';
@@ -2,7 +2,7 @@ import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/i
2
2
  import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
3
3
  import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
4
4
  import type React from 'react';
5
- import { ReactRenderer } from './react-renderer.js';
5
+ import { ReactRenderer } from '../render/react-renderer.js';
6
6
  import type { ReactPluginOptions } from './react.types.js';
7
7
  export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
8
8
  /**
@@ -23,11 +23,15 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
23
23
  private readonly runtimeBundleService;
24
24
  private readonly hmrPageMetadataCache;
25
25
  private readonly clientGraphBoundaryCache;
26
+ private hmrStrategy?;
26
27
  private runtimeDependenciesInitialized;
27
28
  /**
28
- * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
29
+ * When true, always emit page browser graph / hydration assets.
30
+ *
31
+ * @remarks
32
+ * Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
29
33
  */
30
- private readonly explicitGraphEnabled;
34
+ private readonly forceBrowserGraph;
31
35
  private readonly rendererConfig;
32
36
  constructor(options?: ReactPluginOptions);
33
37
  /**
@@ -41,6 +45,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
41
45
  rendererModules?: unknown;
42
46
  }): ReactRenderer;
43
47
  private ensureRuntimeDependencies;
48
+ private resolveEffectiveRuntimeModules;
44
49
  get plugins(): EcoBuildPlugin[];
45
50
  get browserRuntimeManifest(): BrowserRuntimeManifest;
46
51
  /**
@@ -67,6 +72,7 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
67
72
  *
68
73
  * @returns ReactHmrStrategy instance for handling React component updates
69
74
  */
75
+ setHmrManager(hmrManager: NonNullable<IntegrationPlugin['hmrManager']>): void;
70
76
  getHmrStrategy(): HmrStrategy | undefined;
71
77
  }
72
78
  /**
@@ -0,0 +1,241 @@
1
+ import { IntegrationPlugin, } from '@ecopages/core/plugins/integration-plugin';
2
+ import { Logger } from '@ecopages/logger';
3
+ import path from 'node:path';
4
+ import { REACT_PLUGIN_NAME } from './react.constants.js';
5
+ import { ReactRenderer } from '../render/react-renderer.js';
6
+ import { ReactHmrStrategy } from '../hmr/hmr-strategy.js';
7
+ import { ReactDevTransformContributor } from '../dev-transform/react-dev-transform-contributor.js';
8
+ import { RuntimeBundleService } from '../bundling/runtime-bundle.js';
9
+ import { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
10
+ import { createReactMdxLoaderPlugin } from '../mdx/mdx-loader-plugin.js';
11
+ import { appendMdxExtensions, resolveMdxCompilerOptions } from '@ecopages/mdx/core';
12
+ import { ClientGraphBoundaryCache } from '../client-graph/boundary-cache.js';
13
+ import { discoverLayoutRuntimeModuleSpecifiers } from '../bundling/discover-layout-runtime-modules.js';
14
+ import { mergeReactPluginRuntimeModules, resolveReactPluginRuntimeModules } from '../bundling/runtime-modules.js';
15
+ const appLogger = new Logger('[ReactPlugin]');
16
+ /**
17
+ * The name of the React plugin
18
+ */
19
+ export const PLUGIN_NAME = REACT_PLUGIN_NAME;
20
+ const resolveReactMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptions(mdxOptions, { jsxImportSource: 'react' });
21
+ /**
22
+ * Resolves user-facing React plugin options into the internal plugin config.
23
+ *
24
+ * Defaults:
25
+ * - `extensions`: `['.tsx']`
26
+ * - `explicitGraph`: `false`
27
+ * - `mdx.enabled`: `false`
28
+ * - `mdx.extensions`: `['.mdx']`
29
+ */
30
+ const resolveReactPluginOptions = (options) => {
31
+ const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, runtimeModules, ...baseConfig } = options ?? {};
32
+ const extensions = [...(userExtensions ?? ['.tsx'])];
33
+ const mdxEnabled = mdx?.enabled ?? false;
34
+ const mdxExtensions = mdx?.extensions ?? ['.mdx'];
35
+ const resolvedRuntimeModules = resolveReactPluginRuntimeModules(runtimeModules);
36
+ if (mdxEnabled) {
37
+ appendMdxExtensions(extensions, mdxExtensions);
38
+ }
39
+ else if (mdx?.extensions?.length) {
40
+ appLogger.warn('MDX extensions provided but MDX is disabled. MDX files will not be processed. Set mdx.enabled to true to enable MDX support.');
41
+ }
42
+ const rendererConfig = {
43
+ routerAdapter: router,
44
+ runtimeModules: resolvedRuntimeModules,
45
+ mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : undefined,
46
+ mdxExtensions,
47
+ hmrPageMetadataCache: new HmrPageMetadataCache(),
48
+ forceBrowserGraph: explicitGraph ?? false,
49
+ };
50
+ return {
51
+ ...baseConfig,
52
+ extensions,
53
+ integrationDependencies: dependencies,
54
+ rendererConfig,
55
+ };
56
+ };
57
+ /**
58
+ * The React plugin class
59
+ * This plugin provides support for React components in Ecopages
60
+ */
61
+ export class ReactPlugin extends IntegrationPlugin {
62
+ renderer = ReactRenderer;
63
+ routerAdapter;
64
+ mdxEnabled;
65
+ mdxCompilerOptions;
66
+ mdxExtensions;
67
+ mdxLoaderPlugin;
68
+ runtimeBundleService;
69
+ hmrPageMetadataCache;
70
+ clientGraphBoundaryCache;
71
+ hmrStrategy;
72
+ runtimeDependenciesInitialized = false;
73
+ /**
74
+ * When true, always emit page browser graph / hydration assets.
75
+ *
76
+ * @remarks
77
+ * Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
78
+ */
79
+ forceBrowserGraph;
80
+ rendererConfig;
81
+ constructor(options) {
82
+ const config = resolveReactPluginOptions(options);
83
+ const { extensions, rendererConfig, integrationDependencies, ...baseConfig } = config;
84
+ super({
85
+ name: PLUGIN_NAME,
86
+ extensions,
87
+ jsxImportSource: 'react',
88
+ integrationDependencies,
89
+ ...baseConfig,
90
+ });
91
+ this.routerAdapter = rendererConfig.routerAdapter;
92
+ this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
93
+ this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
94
+ this.mdxExtensions = rendererConfig.mdxExtensions ?? ['.mdx'];
95
+ this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new HmrPageMetadataCache();
96
+ this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
97
+ this.forceBrowserGraph = rendererConfig.forceBrowserGraph ?? false;
98
+ this.rendererConfig = {
99
+ ...rendererConfig,
100
+ mdxExtensions: this.mdxExtensions,
101
+ hmrPageMetadataCache: this.hmrPageMetadataCache,
102
+ forceBrowserGraph: this.forceBrowserGraph,
103
+ clientGraphBoundaryCache: this.clientGraphBoundaryCache,
104
+ };
105
+ if (this.mdxEnabled) {
106
+ appLogger.debug('MDX mode enabled with React jsx runtime');
107
+ }
108
+ this.runtimeBundleService = new RuntimeBundleService({
109
+ routerAdapter: this.routerAdapter,
110
+ runtimeModules: this.rendererConfig.runtimeModules,
111
+ });
112
+ }
113
+ /**
114
+ * Creates a React renderer with instance-owned runtime configuration.
115
+ *
116
+ * React renderers depend on plugin-owned router, MDX, and HMR metadata state.
117
+ * Keeping that state on the instance avoids cross-plugin static mutation while
118
+ * preserving the same runtime services the base initializer wires up.
119
+ */
120
+ initializeRenderer(options) {
121
+ const renderer = new this.renderer({
122
+ ...this.createRendererOptions(options),
123
+ reactConfig: this.rendererConfig,
124
+ });
125
+ return this.attachRendererRuntimeServices(renderer);
126
+ }
127
+ ensureRuntimeDependencies() {
128
+ if (this.runtimeDependenciesInitialized) {
129
+ return;
130
+ }
131
+ this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
132
+ this.runtimeBundleService.setWorkDir(this.appConfig?.absolutePaths?.workDir ??
133
+ (this.appConfig?.rootDir
134
+ ? path.join(this.appConfig.rootDir, this.appConfig.workDir ?? '.eco')
135
+ : undefined));
136
+ this.runtimeBundleService.setRuntimeModules(this.resolveEffectiveRuntimeModules());
137
+ this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
138
+ this.runtimeDependenciesInitialized = true;
139
+ }
140
+ resolveEffectiveRuntimeModules() {
141
+ const manualModules = this.rendererConfig.runtimeModules ?? [];
142
+ if (!this.routerAdapter || !this.appConfig) {
143
+ return manualModules;
144
+ }
145
+ const discovery = discoverLayoutRuntimeModuleSpecifiers({
146
+ searchDirs: [this.appConfig.absolutePaths.layoutsDir, this.appConfig.absolutePaths.componentsDir].filter(Boolean),
147
+ projectRoot: this.appConfig.absolutePaths.projectDir,
148
+ routerImportPath: this.routerAdapter.bundle.importPath,
149
+ });
150
+ const merged = mergeReactPluginRuntimeModules(manualModules, discovery.specifiers);
151
+ this.rendererConfig.runtimeModules = merged;
152
+ if (discovery.mode === 'provider-scoped-fallback') {
153
+ appLogger.debug('Layout runtime auto-vendoring is using provider-scoped fallback discovery. Set runtimeProvider: true on provider root layouts to scope discovery explicitly.');
154
+ }
155
+ if (discovery.specifiers.length > 0) {
156
+ appLogger.debug(`Auto-vendoring layout runtime modules for persisted SPA layouts: ${discovery.specifiers.join(', ')}`);
157
+ }
158
+ return merged;
159
+ }
160
+ get plugins() {
161
+ if (this.mdxLoaderPlugin) {
162
+ return [this.mdxLoaderPlugin];
163
+ }
164
+ return [];
165
+ }
166
+ get browserRuntimeManifest() {
167
+ this.ensureRuntimeDependencies();
168
+ return this.runtimeBundleService.getRuntimeManifest();
169
+ }
170
+ /**
171
+ * Ensures the optional React MDX loader exists before either config-time
172
+ * manifest sealing or runtime setup needs it.
173
+ */
174
+ async ensureMdxLoaderPlugin() {
175
+ if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
176
+ return;
177
+ }
178
+ this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
179
+ }
180
+ /**
181
+ * Prepares React's build-facing loader contributions before config build seals
182
+ * the app manifest.
183
+ */
184
+ async prepareBuildContributions() {
185
+ this.ensureRuntimeDependencies();
186
+ await this.ensureMdxLoaderPlugin();
187
+ }
188
+ /**
189
+ * Performs runtime-only React setup after build contributions are already
190
+ * materialized.
191
+ */
192
+ async setup() {
193
+ this.ensureRuntimeDependencies();
194
+ await this.ensureMdxLoaderPlugin();
195
+ await super.setup();
196
+ }
197
+ /**
198
+ * Provides React-specific HMR strategy with Fast Refresh support.
199
+ *
200
+ * The strategy shares a React-only page metadata cache with the renderer so
201
+ * save-time rebuilds can reuse declared-module analysis without expanding the
202
+ * core HMR interfaces.
203
+ *
204
+ * @returns ReactHmrStrategy instance for handling React component updates
205
+ */
206
+ setHmrManager(hmrManager) {
207
+ super.setHmrManager(hmrManager);
208
+ const strategy = this.getHmrStrategy();
209
+ if (!strategy || !this.appConfig) {
210
+ return;
211
+ }
212
+ hmrManager.registerDevTransformContributor(new ReactDevTransformContributor({
213
+ strategy: strategy,
214
+ }));
215
+ }
216
+ getHmrStrategy() {
217
+ if (!this.hmrManager || !this.appConfig) {
218
+ return undefined;
219
+ }
220
+ if (!this.hmrStrategy) {
221
+ this.hmrStrategy = new ReactHmrStrategy({
222
+ context: this.hmrManager.getDefaultContext(),
223
+ pageMetadataCache: this.hmrPageMetadataCache,
224
+ runtimeManifest: this.runtimeBundleService.getRuntimeManifest('development'),
225
+ mdxCompilerOptions: this.mdxCompilerOptions,
226
+ ownedTemplateExtensions: this.extensions,
227
+ allTemplateExtensions: this.appConfig.templatesExt,
228
+ clientGraphBoundaryCache: this.clientGraphBoundaryCache,
229
+ });
230
+ }
231
+ return this.hmrStrategy;
232
+ }
233
+ }
234
+ /**
235
+ * Factory function to create a React plugin instance
236
+ * @param options Configuration options for the React plugin
237
+ * @returns A new ReactPlugin instance
238
+ */
239
+ export function reactPlugin(options) {
240
+ return new ReactPlugin(options);
241
+ }
@@ -0,0 +1,156 @@
1
+ import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
2
+ import type { CompileOptions } from '@mdx-js/mdx';
3
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
4
+ import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
5
+ import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from '../bundling/runtime-modules.js';
6
+ import type { ClientGraphBoundaryCache } from '../client-graph/boundary-cache.js';
7
+ /**
8
+ * MDX configuration options for the React plugin.
9
+ */
10
+ export type ReactMdxOptions = {
11
+ /**
12
+ * Whether to enable MDX support.
13
+ * @default false
14
+ */
15
+ enabled: boolean;
16
+ /**
17
+ * Compiler options for MDX.
18
+ * @default undefined
19
+ */
20
+ compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
21
+ /**
22
+ * Remark plugins.
23
+ * @default undefined
24
+ */
25
+ remarkPlugins?: CompileOptions['remarkPlugins'];
26
+ /**
27
+ * Rehype plugins.
28
+ * @default undefined
29
+ */
30
+ rehypePlugins?: CompileOptions['rehypePlugins'];
31
+ /**
32
+ * Recma plugins.
33
+ * @default undefined
34
+ */
35
+ recmaPlugins?: CompileOptions['recmaPlugins'];
36
+ /**
37
+ * Custom extensions to be treated as MDX files.
38
+ * @default ['.mdx']
39
+ */
40
+ extensions?: string[];
41
+ };
42
+ /**
43
+ * Options for the React plugin.
44
+ */
45
+ export type ReactPluginOptions = {
46
+ extensions?: string[];
47
+ dependencies?: AssetDefinition[];
48
+ /**
49
+ * When true, always emit the page browser graph / hydration assets for React
50
+ * page entries, even when the page does not declare `dependencies.modules`
51
+ * and no router adapter is configured.
52
+ *
53
+ * @remarks
54
+ * This does not skip the client-graph AST boundary. Server-only
55
+ * `eco.page(...)` options such as `middleware` and `requires` are still
56
+ * stripped from browser bundles.
57
+ *
58
+ * With a router adapter, page hydration is already always enabled, so this
59
+ * option is redundant for SPA apps.
60
+ *
61
+ * @default false
62
+ */
63
+ explicitGraph?: boolean;
64
+ /**
65
+ * Router adapter for SPA navigation.
66
+ * When provided, pages with layouts will be wrapped in the router for client-side navigation.
67
+ * @example
68
+ * ```ts
69
+ * import { ecoRouter } from '@ecopages/react-router';
70
+ * reactPlugin({ router: ecoRouter() })
71
+ * ```
72
+ */
73
+ router?: ReactRouterAdapter;
74
+ /**
75
+ * Optional shared browser runtime vendors.
76
+ *
77
+ * With `router`, npm packages reachable from `eco.layout()` **render graphs**
78
+ * under the app's configured `layouts/` and `components/` directories are
79
+ * discovered automatically and registered as shared vendors (alongside React
80
+ * and React DOM). This prevents duplicate module instances when persisted
81
+ * layouts stay mounted across SPA navigation.
82
+ *
83
+ * Without `router`, only explicit entries here are vendored.
84
+ *
85
+ * @remarks
86
+ * Discovery follows client reachability from each layout's `render` path,
87
+ * resolves relative and tsconfig path aliases, and collects npm package roots
88
+ * imported from provider/context modules in that graph (for example files named
89
+ * `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
90
+ * It does not vendor every npm dependency reachable from shell or page UI.
91
+ *
92
+ * Layouts that mount shared runtime state should set `runtimeProvider: true` in
93
+ * `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
94
+ * vendor every reachable npm package in that layout graph. When no layout opts
95
+ * in, discovery falls back to scanning all layouts with provider-scoped npm
96
+ * collection.
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * export const QueryRootLayout = eco.layout({
101
+ * runtimeProvider: true,
102
+ * render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
103
+ * });
104
+ *
105
+ * reactPlugin({
106
+ * router: ecoRouter(),
107
+ * });
108
+ * ```
109
+ *
110
+ * Manual entries override auto-discovered entries for the same specifier.
111
+ * Subpath imports such as `@acme/ui/button` dedupe to the registered package
112
+ * root vendor URL when `@acme/ui` is configured here or auto-discovered.
113
+ *
114
+ * @example Advanced vendor config
115
+ * ```ts
116
+ * runtimeModules: [
117
+ * { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] },
118
+ * ]
119
+ * ```
120
+ */
121
+ runtimeModules?: ReactPluginRuntimeModule[];
122
+ /**
123
+ * MDX configuration for handling .mdx files within the React plugin.
124
+ * When enabled, MDX files are treated as React pages with full router support.
125
+ * @example
126
+ * ```ts
127
+ * reactPlugin({
128
+ * router: ecoRouter(),
129
+ * mdx: {
130
+ * enabled: true,
131
+ * extensions: ['.mdx', '.md'],
132
+ * remarkPlugins: [remarkGfm],
133
+ * rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
134
+ * }
135
+ * })
136
+ * ```
137
+ */
138
+ mdx?: ReactMdxOptions;
139
+ };
140
+ export type ReactRendererConfig = {
141
+ routerAdapter?: ReactRouterAdapter;
142
+ runtimeModules?: ResolvedReactPluginRuntimeModule[];
143
+ mdxCompilerOptions?: CompileOptions;
144
+ mdxExtensions?: string[];
145
+ hmrPageMetadataCache?: HmrPageMetadataCache;
146
+ /** Persistent React-plugin-owned cache shared by bundles and HMR transforms. */
147
+ clientGraphBoundaryCache?: ClientGraphBoundaryCache;
148
+ /**
149
+ * When true, always emit page browser graph / hydration assets for React pages.
150
+ *
151
+ * @remarks
152
+ * Mapped from the public `explicitGraph` plugin option. Does not skip the
153
+ * client-graph AST strip of server-only `eco.page(...)` options.
154
+ */
155
+ forceBrowserGraph?: boolean;
156
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Ownership helpers for deciding whether a component stays in the React render lane.
3
+ */
4
+ import type { EcoComponent, EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
5
+ import type { FunctionComponent } from 'react';
6
+ export type SerializableProps = Record<string, unknown>;
7
+ export type ReactRenderableComponent<P extends SerializableProps = SerializableProps> = FunctionComponent<P> & {
8
+ config?: EcoComponentConfig;
9
+ requires?: string | readonly string[];
10
+ };
11
+ export type RequiresAwareComponent = {
12
+ requires?: string | readonly string[];
13
+ };
14
+ /**
15
+ * Reads the declared integration name for a component or layout.
16
+ *
17
+ * @remarks
18
+ * Honors both the explicit `config.integration` override and build-time
19
+ * `getComponentIdentity(component)?.integration` attribution.
20
+ */
21
+ export declare function getComponentIntegration(component?: {
22
+ config?: EcoComponentConfig;
23
+ } | null): string | undefined;
24
+ /**
25
+ * Returns whether a component should stay inside the React render lane.
26
+ *
27
+ * @remarks
28
+ * Components without explicit integration metadata are treated as React-owned
29
+ * because this renderer only receives them after the route pipeline has already
30
+ * selected the React integration.
31
+ */
32
+ export declare function isReactManagedComponent(component: {
33
+ config?: EcoComponentConfig;
34
+ } | null | undefined, reactIntegrationName: string): boolean;
35
+ export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
36
+ /**
37
+ * Commits a framework-agnostic component to React semantics.
38
+ *
39
+ * @remarks
40
+ * Core keeps `EcoComponent` broad so integrations can share the same public surface;
41
+ * once the React renderer is executing, `createElement()` needs a concrete React
42
+ * component signature.
43
+ */
44
+ export declare function asReactComponent<P extends SerializableProps>(component: unknown): ReactRenderableComponent<P>;
45
+ /**
46
+ * Commits a mixed-shell component to the string-returning contract required by
47
+ * non-React layouts and HTML templates.
48
+ */
49
+ export declare function asNonReactShellComponent<P extends SerializableProps>(component: unknown): (props: P) => EcoPagesElement | Promise<EcoPagesElement>;
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Ownership helpers for deciding whether a component stays in the React render lane.
3
+ */
4
+ /**
5
+ * Reads the declared integration name for a component or layout.
6
+ *
7
+ * @remarks
8
+ * Honors both the explicit `config.integration` override and build-time
9
+ * `getComponentIdentity(component)?.integration` attribution.
10
+ */
11
+ export function getComponentIntegration(component) {
12
+ return component?.config?.integration ?? component?.config?.identity?.integration;
13
+ }
14
+ /**
15
+ * Returns whether a component should stay inside the React render lane.
16
+ *
17
+ * @remarks
18
+ * Components without explicit integration metadata are treated as React-owned
19
+ * because this renderer only receives them after the route pipeline has already
20
+ * selected the React integration.
21
+ */
22
+ export function isReactManagedComponent(component, reactIntegrationName) {
23
+ const integration = getComponentIntegration(component);
24
+ return integration === undefined || integration === reactIntegrationName;
25
+ }
26
+ export function getComponentRequires(component) {
27
+ return component?.requires;
28
+ }
29
+ /**
30
+ * Commits a framework-agnostic component to React semantics.
31
+ *
32
+ * @remarks
33
+ * Core keeps `EcoComponent` broad so integrations can share the same public surface;
34
+ * once the React renderer is executing, `createElement()` needs a concrete React
35
+ * component signature.
36
+ */
37
+ export function asReactComponent(component) {
38
+ return component;
39
+ }
40
+ /**
41
+ * Commits a mixed-shell component to the string-returning contract required by
42
+ * non-React layouts and HTML templates.
43
+ */
44
+ export function asNonReactShellComponent(component) {
45
+ return component;
46
+ }