@ecopages/react 0.2.0-beta.3 → 0.2.0-beta.30

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 (109) hide show
  1. package/README.md +168 -6
  2. package/package.json +51 -26
  3. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  4. package/src/bundling/bootstrap-package-paths.js +6 -0
  5. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +21 -8
  6. package/src/{services/react-bundle.service.js → bundling/bundle.js} +53 -21
  7. package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
  8. package/src/bundling/discover-layout-runtime-modules.js +180 -0
  9. package/src/bundling/runtime-alias-map.d.ts +10 -0
  10. package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +13 -2
  11. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +30 -5
  12. package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +104 -8
  13. package/src/bundling/runtime-mode.d.ts +9 -0
  14. package/src/bundling/runtime-mode.js +6 -0
  15. package/src/bundling/runtime-modules.d.ts +29 -0
  16. package/src/bundling/runtime-modules.js +38 -0
  17. package/src/client-graph/ast-transform.d.ts +18 -0
  18. package/src/{utils/client-graph-boundary-plugin.js → client-graph/ast-transform.js} +15 -232
  19. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
  20. package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
  21. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
  22. package/src/client-graph/boundary-plugin.js +107 -0
  23. package/src/{utils → client-graph}/component-config-traversal.js +4 -2
  24. package/src/{utils → client-graph}/reachability-analyzer.d.ts +2 -2
  25. package/src/{utils → client-graph}/reachability-analyzer.js +4 -1
  26. package/src/client-graph/specifier-classification.d.ts +75 -0
  27. package/src/client-graph/specifier-classification.js +155 -0
  28. package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +19 -6
  29. package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +154 -133
  30. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  31. package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
  32. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  33. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  34. package/src/hydration/bootstrap-imports.d.ts +25 -0
  35. package/src/hydration/bootstrap-imports.js +23 -0
  36. package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
  37. package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +63 -56
  38. package/src/hydration/hydration-scripts.d.ts +100 -0
  39. package/src/hydration/hydration-scripts.js +350 -0
  40. package/src/{utils → hydration}/hydration-scripts.test.browser.js +11 -5
  41. package/src/hydration/page-data-manifest.d.ts +58 -0
  42. package/src/hydration/page-data-manifest.js +53 -0
  43. package/src/hydration/page-data-reader.d.ts +31 -0
  44. package/src/hydration/page-data-reader.js +64 -0
  45. package/src/hydration/page-payload.d.ts +67 -0
  46. package/src/hydration/page-payload.js +104 -0
  47. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  48. package/src/hydration/serialize-page-data-script.js +31 -0
  49. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
  50. package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +8 -10
  51. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  52. package/src/mdx/mdx-loader-plugin.js +11 -0
  53. package/src/page/page-module.d.ts +46 -0
  54. package/src/page/page-module.js +72 -0
  55. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +8 -3
  56. package/src/{react.plugin.js → plugin/react.plugin.js} +78 -54
  57. package/src/plugin/react.types.d.ts +149 -0
  58. package/src/render/component-ownership.d.ts +50 -0
  59. package/src/render/component-ownership.js +23 -0
  60. package/src/render/component-ssr.d.ts +113 -0
  61. package/src/render/component-ssr.js +202 -0
  62. package/src/render/errors.d.ts +16 -0
  63. package/src/render/errors.js +18 -0
  64. package/src/render/layout-compose.d.ts +66 -0
  65. package/src/render/layout-compose.js +106 -0
  66. package/src/render/react-renderer.d.ts +138 -0
  67. package/src/render/react-renderer.js +481 -0
  68. package/src/render/react-runtime.d.ts +13 -0
  69. package/src/render/react-runtime.js +21 -0
  70. package/src/render/unified-layout-composition.d.ts +53 -0
  71. package/src/render/unified-layout-composition.js +89 -0
  72. package/src/react-renderer.d.ts +0 -233
  73. package/src/react-renderer.js +0 -622
  74. package/src/react.types.d.ts +0 -88
  75. package/src/services/pages-index.d.ts +0 -64
  76. package/src/services/pages-index.js +0 -73
  77. package/src/services/react-page-module.service.d.ts +0 -88
  78. package/src/services/react-page-module.service.js +0 -166
  79. package/src/services/react-page-payload.service.d.ts +0 -46
  80. package/src/services/react-page-payload.service.js +0 -67
  81. package/src/utils/hydration-scripts.d.ts +0 -92
  82. package/src/utils/hydration-scripts.js +0 -358
  83. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  84. package/src/utils/react-mdx-loader-plugin.js +0 -45
  85. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  86. /package/src/{utils → app}/client-only.d.ts +0 -0
  87. /package/src/{utils → app}/client-only.js +0 -0
  88. /package/src/{utils → app}/dynamic.d.ts +0 -0
  89. /package/src/{utils → app}/dynamic.js +0 -0
  90. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  91. /package/src/{utils → app}/dynamic.test.browser.js +0 -0
  92. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  93. /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
  94. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  95. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  96. /package/src/{utils → client-graph}/declared-modules.js +0 -0
  97. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  98. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  99. /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
  100. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  101. /package/src/{utils → hmr}/hmr-scripts.js +0 -0
  102. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  103. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  104. /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
  105. /package/src/{react.types.js → plugin/react.types.js} +0 -0
  106. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  107. /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
  108. /package/src/{utils → render}/html-boundary.d.ts +0 -0
  109. /package/src/{utils → render}/html-boundary.js +0 -0
@@ -0,0 +1,104 @@
1
+ import { LocalsAccessError } from "@ecopages/core/errors";
2
+ import {
3
+ serializePageDataManifestScript,
4
+ serializePageDataScript
5
+ } from "./serialize-page-data-script.js";
6
+ import { isReactManagedComponent } from "../render/component-ownership.js";
7
+ class PagePayloadService {
8
+ /**
9
+ * Resolves the browser-importable page module URL from processed page entry assets.
10
+ */
11
+ resolvePageModuleUrl(pagePackage, options) {
12
+ if (!options.routerEnabled) {
13
+ return void 0;
14
+ }
15
+ const entryScripts = pagePackage?.pageBrowserGraph?.entryAssets.filter(
16
+ (asset) => asset.kind === "script" && typeof asset.srcUrl === "string"
17
+ ) ?? [];
18
+ const bootstrapScript = entryScripts.find(
19
+ (asset) => asset.attributes?.["data-eco-page-bootstrap"] === "react-router"
20
+ );
21
+ return bootstrapScript?.srcUrl ?? entryScripts[0]?.srcUrl;
22
+ }
23
+ /**
24
+ * Creates the `__ECO_PAGE_DATA__` script for router hydration.
25
+ *
26
+ * @remarks
27
+ * When `moduleUrl` is present, emits the v1 envelope via
28
+ * {@link serializePageDataManifestScript}. Otherwise emits legacy flat props
29
+ * for non-router shells.
30
+ */
31
+ buildRouterPageDataScript(pageProps, moduleUrl) {
32
+ const props = { ...pageProps ?? {} };
33
+ if (moduleUrl) {
34
+ return serializePageDataManifestScript({ moduleUrl, props });
35
+ }
36
+ return serializePageDataScript(props);
37
+ }
38
+ /**
39
+ * Builds shared document html contributions for router-backed React pages rendered
40
+ * through a non-React HTML shell.
41
+ */
42
+ buildNonReactDocumentContributions(options) {
43
+ if (isReactManagedComponent(options.htmlTemplate, options.reactIntegrationName) || !options.routerEnabled) {
44
+ return void 0;
45
+ }
46
+ return [
47
+ {
48
+ placement: "head-append",
49
+ html: this.buildRouterPageDataScript(options.pageProps, options.pageModuleUrl)
50
+ }
51
+ ];
52
+ }
53
+ /**
54
+ * Builds the browser-safe page-props object embedded into the final HTML.
55
+ *
56
+ * @remarks
57
+ * Narrower than the full server render input: only routing data, public page
58
+ * props, and explicitly allowed locals. Page module identity is threaded via
59
+ * `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
60
+ */
61
+ buildSerializedPageProps(options) {
62
+ return {
63
+ ...options.pageProps,
64
+ params: options.params,
65
+ query: options.query,
66
+ ...options.safeLocals && { locals: options.safeLocals }
67
+ };
68
+ }
69
+ /**
70
+ * Extracts the declared subset of locals for client-side hydration.
71
+ *
72
+ * @remarks
73
+ * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
74
+ * request-scoped data. Only keys declared via `Page.requires` are serialized.
75
+ * On static pages, `locals` is a Proxy that throws `LocalsAccessError`; this
76
+ * method returns `undefined` instead of throwing.
77
+ */
78
+ getSerializableLocals(locals, requiredLocals) {
79
+ try {
80
+ if (!locals) {
81
+ return void 0;
82
+ }
83
+ const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
84
+ if (requiredKeys.length === 0) {
85
+ return void 0;
86
+ }
87
+ const serializedLocals = Object.fromEntries(
88
+ requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
89
+ );
90
+ if (Object.keys(serializedLocals).length > 0) {
91
+ return serializedLocals;
92
+ }
93
+ return void 0;
94
+ } catch (error) {
95
+ if (error instanceof LocalsAccessError) {
96
+ return void 0;
97
+ }
98
+ throw error;
99
+ }
100
+ }
101
+ }
102
+ export {
103
+ PagePayloadService
104
+ };
@@ -0,0 +1,27 @@
1
+ import { type EcoPageDataDocumentPayload, type EcoPageDataProps } from './page-data-manifest.js';
2
+ export { ECO_PAGE_DATA_SCHEMA_VERSION, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolvePageDataDocumentPayload, type EcoPageDataDocumentPayload, type EcoPageDataManifestV1, type EcoPageDataProps, } from './page-data-manifest.js';
3
+ /**
4
+ * Escapes page data JSON for safe embedding in HTML script bodies.
5
+ */
6
+ export declare function escapePageDataJson(pageProps: EcoPageDataDocumentPayload | undefined): string;
7
+ /**
8
+ * Emits the canonical `__ECO_PAGE_DATA__` bootstrap script tag.
9
+ *
10
+ * @remarks
11
+ * Accepts a v1 envelope or legacy flat props. Router-enabled documents should
12
+ * use {@link serializePageDataManifestScript} so clients can discover the page
13
+ * module without parsing hydration JavaScript.
14
+ */
15
+ export declare function serializePageDataScript(pageProps: EcoPageDataDocumentPayload | undefined): string;
16
+ /**
17
+ * Emits a versioned page-data envelope for React router documents.
18
+ *
19
+ * @remarks
20
+ * Canonical HTML serializer for router-enabled pages. SPA commit paths that
21
+ * build a React element instead of an HTML string use
22
+ * {@link resolvePageDataDocumentPayload} with the same envelope shape.
23
+ */
24
+ export declare function serializePageDataManifestScript(input: {
25
+ moduleUrl: string;
26
+ props: EcoPageDataProps;
27
+ }): string;
@@ -0,0 +1,31 @@
1
+ import {
2
+ createEcoPageDataManifestV1
3
+ } from "./page-data-manifest.js";
4
+ import {
5
+ ECO_PAGE_DATA_SCHEMA_VERSION,
6
+ createEcoPageDataManifestV1 as createEcoPageDataManifestV12,
7
+ isEcoPageDataManifestV1,
8
+ resolveEcoPageDataModuleUrl,
9
+ resolveEcoPageDataProps,
10
+ resolvePageDataDocumentPayload
11
+ } from "./page-data-manifest.js";
12
+ function escapePageDataJson(pageProps) {
13
+ return JSON.stringify(pageProps ?? {}).replace(/</g, "\\u003c");
14
+ }
15
+ function serializePageDataScript(pageProps) {
16
+ return `<script id="__ECO_PAGE_DATA__" type="application/json">${escapePageDataJson(pageProps)}<\/script>`;
17
+ }
18
+ function serializePageDataManifestScript(input) {
19
+ return serializePageDataScript(createEcoPageDataManifestV1(input));
20
+ }
21
+ export {
22
+ ECO_PAGE_DATA_SCHEMA_VERSION,
23
+ createEcoPageDataManifestV12 as createEcoPageDataManifestV1,
24
+ escapePageDataJson,
25
+ isEcoPageDataManifestV1,
26
+ resolveEcoPageDataModuleUrl,
27
+ resolveEcoPageDataProps,
28
+ resolvePageDataDocumentPayload,
29
+ serializePageDataManifestScript,
30
+ serializePageDataScript
31
+ };
@@ -1,10 +1,10 @@
1
1
  import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
2
2
  import { type AssetProcessingService, type ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
3
- import type { ReactPageModuleService } from './react-page-module.service.js';
3
+ import type { PageModuleService } from '../page/page-module.js';
4
4
  type MdxConfigDependencyProcessor = (components: Partial<EcoComponent>[]) => Promise<ProcessedAsset[]>;
5
- export interface ReactMdxConfigDependencyServiceConfig {
5
+ export interface MdxConfigDependencyServiceConfig {
6
6
  integrationName: string;
7
- pageModuleService: Pick<ReactPageModuleService, 'ensureConfigFileMetadata'>;
7
+ pageModuleService: Pick<PageModuleService, 'ensureConfigFileMetadata'>;
8
8
  assetProcessingService?: Pick<AssetProcessingService, 'processDependencies'>;
9
9
  }
10
10
  /**
@@ -15,9 +15,9 @@ export interface ReactMdxConfigDependencyServiceConfig {
15
15
  * component configs so the shared dependency pipeline can process them without
16
16
  * growing more MDX-specific logic inside the renderer.
17
17
  */
18
- export declare class ReactMdxConfigDependencyService {
18
+ export declare class MdxConfigDependencyService {
19
19
  private readonly config;
20
- constructor(config: ReactMdxConfigDependencyServiceConfig);
20
+ constructor(config: MdxConfigDependencyServiceConfig);
21
21
  /**
22
22
  * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
23
23
  */
@@ -3,8 +3,8 @@ import { rapidhash } from "@ecopages/core/hash";
3
3
  import {
4
4
  AssetFactory
5
5
  } from "@ecopages/core/services/asset-processing-service";
6
- import { collectFromConfigForest, getComponentConfigs } from "../utils/component-config-traversal.js";
7
- class ReactMdxConfigDependencyService {
6
+ import { collectFromConfigForest, getComponentConfigs } from "../client-graph/component-config-traversal.js";
7
+ class MdxConfigDependencyService {
8
8
  config;
9
9
  constructor(config) {
10
10
  this.config = config;
@@ -23,13 +23,11 @@ class ReactMdxConfigDependencyService {
23
23
  }
24
24
  createOwnedConfigComponents(pagePath, config) {
25
25
  const components = [];
26
- const resolvedLayout = config?.layout;
27
- if (resolvedLayout?.config?.dependencies) {
28
- const layoutConfig = this.config.pageModuleService.ensureConfigFileMetadata(
29
- resolvedLayout.config,
30
- pagePath
31
- );
32
- components.push({ config: layoutConfig });
26
+ for (const layout of config?.layouts ?? []) {
27
+ if (layout?.config?.dependencies) {
28
+ const layoutConfig = this.config.pageModuleService.ensureConfigFileMetadata(layout.config, pagePath);
29
+ components.push({ config: layoutConfig });
30
+ }
33
31
  }
34
32
  if (config?.dependencies) {
35
33
  components.push({
@@ -118,5 +116,5 @@ class ReactMdxConfigDependencyService {
118
116
  }
119
117
  }
120
118
  export {
121
- ReactMdxConfigDependencyService
119
+ MdxConfigDependencyService
122
120
  };
@@ -0,0 +1,2 @@
1
+ import type { CompileOptions } from '@mdx-js/mdx';
2
+ export declare function createReactMdxLoaderPlugin(compilerOptions?: CompileOptions): import("@ecopages/core/build/build-types").EcoBuildPlugin;
@@ -0,0 +1,11 @@
1
+ import { createMdxLoaderPlugin as createMdxLoaderPluginCore } from "@ecopages/mdx/core";
2
+ function createReactMdxLoaderPlugin(compilerOptions) {
3
+ return createMdxLoaderPluginCore({
4
+ name: "react-mdx-loader",
5
+ compilerOptions,
6
+ defaultMdExtensions: []
7
+ });
8
+ }
9
+ export {
10
+ createReactMdxLoaderPlugin
11
+ };
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Page module loading and configuration resolution service for React integration.
3
+ *
4
+ * Handles component config metadata 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, 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 proper `__eco` metadata 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,72 @@
1
+ import path from "node:path";
2
+ import { rapidhash } from "@ecopages/core/hash";
3
+ import { fileSystem } from "@ecopages/file-system";
4
+ import { someInConfigTree } from "../client-graph/component-config-traversal.js";
5
+ import { collectPageDeclaredModulesFromModule } from "../client-graph/declared-modules.js";
6
+ class PageModuleService {
7
+ config;
8
+ constructor(config) {
9
+ this.config = config;
10
+ }
11
+ /**
12
+ * Checks if the given file path corresponds to an MDX file based on configured extensions.
13
+ */
14
+ isMdxFile(filePath) {
15
+ return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
16
+ }
17
+ /**
18
+ * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
19
+ */
20
+ ensureConfigFileMetadata(config, pagePath) {
21
+ if (config.__eco?.file) {
22
+ return config;
23
+ }
24
+ const buildEcoMeta = (file) => ({
25
+ id: config.__eco?.id ?? rapidhash(file).toString(36),
26
+ integration: config.__eco?.integration ?? this.config.integrationName,
27
+ file
28
+ });
29
+ const resolveDependencyValue = (value) => typeof value === "string" ? value : value.src;
30
+ const dependencyPaths = [
31
+ ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
32
+ ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue)
33
+ ].filter((value) => Boolean(value)).filter((value) => value.startsWith("./") || value.startsWith("../"));
34
+ const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter(
35
+ (value) => typeof value === "string" && value.length > 0
36
+ );
37
+ for (const dependencyPath of dependencyPaths) {
38
+ for (const candidateDir of candidateDirs) {
39
+ const resolvedDependency = path.resolve(candidateDir, dependencyPath);
40
+ if (fileSystem.exists(resolvedDependency)) {
41
+ return {
42
+ ...config,
43
+ __eco: buildEcoMeta(path.join(candidateDir, path.basename(pagePath)))
44
+ };
45
+ }
46
+ }
47
+ }
48
+ return {
49
+ ...config,
50
+ __eco: buildEcoMeta(pagePath)
51
+ };
52
+ }
53
+ hasModulesInConfig(config) {
54
+ return someInConfigTree(
55
+ config,
56
+ (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false
57
+ );
58
+ }
59
+ shouldHydratePage(pageModule) {
60
+ if (this.config.hasRouterAdapter) {
61
+ return true;
62
+ }
63
+ const pageConfig = pageModule.default?.config;
64
+ return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
65
+ }
66
+ collectPageDeclaredModules(pageModule) {
67
+ return collectPageDeclaredModulesFromModule(pageModule);
68
+ }
69
+ }
70
+ export {
71
+ PageModuleService
72
+ };
@@ -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
  /**
@@ -2,47 +2,34 @@ import {
2
2
  IntegrationPlugin
3
3
  } from "@ecopages/core/plugins/integration-plugin";
4
4
  import { Logger } from "@ecopages/logger";
5
+ import path from "node:path";
5
6
  import { REACT_PLUGIN_NAME } from "./react.constants.js";
6
- import { ReactRenderer } from "./react-renderer.js";
7
- import { ReactHmrStrategy } from "./react-hmr-strategy.js";
8
- import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.service.js";
9
- import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
10
- import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
11
- import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
7
+ import { ReactRenderer } from "../render/react-renderer.js";
8
+ import { ReactHmrStrategy } from "../hmr/hmr-strategy.js";
9
+ import { RuntimeBundleService } from "../bundling/runtime-bundle.js";
10
+ import { HmrPageMetadataCache } from "../hmr/page-metadata-cache.js";
11
+ import { createReactMdxLoaderPlugin } from "../mdx/mdx-loader-plugin.js";
12
+ import { appendMdxExtensions, resolveMdxCompilerOptions } from "@ecopages/mdx/core";
13
+ import { ClientGraphBoundaryCache } from "../client-graph/boundary-cache.js";
14
+ import { discoverLayoutRuntimeModuleSpecifiers } from "../bundling/discover-layout-runtime-modules.js";
15
+ import { mergeReactPluginRuntimeModules, resolveReactPluginRuntimeModules } from "../bundling/runtime-modules.js";
12
16
  const appLogger = new Logger("[ReactPlugin]");
13
17
  const PLUGIN_NAME = REACT_PLUGIN_NAME;
14
- const mergePluginLists = (...lists) => {
15
- const merged = lists.flatMap((list) => list ? [...list] : []);
16
- return merged.length > 0 ? merged : void 0;
17
- };
18
- const appendMdxExtensions = (target, mdxExtensions) => {
19
- for (const extension of mdxExtensions) {
20
- if (!target.includes(extension)) {
21
- target.push(extension);
22
- }
23
- }
24
- };
25
- const resolveReactMdxCompilerOptions = (mdxOptions) => {
26
- const { compilerOptions, remarkPlugins, rehypePlugins, recmaPlugins } = mdxOptions;
27
- const resolved = {
28
- ...compilerOptions,
29
- jsxImportSource: "react",
30
- jsxRuntime: "automatic",
31
- development: process.env.NODE_ENV === "development"
32
- };
33
- const mergedRemark = mergePluginLists(compilerOptions?.remarkPlugins, remarkPlugins);
34
- const mergedRehype = mergePluginLists(compilerOptions?.rehypePlugins, rehypePlugins);
35
- const mergedRecma = mergePluginLists(compilerOptions?.recmaPlugins, recmaPlugins);
36
- if (mergedRemark) resolved.remarkPlugins = mergedRemark;
37
- if (mergedRehype) resolved.rehypePlugins = mergedRehype;
38
- if (mergedRecma) resolved.recmaPlugins = mergedRecma;
39
- return resolved;
40
- };
18
+ const resolveReactMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptions(mdxOptions, { jsxImportSource: "react" });
41
19
  const resolveReactPluginOptions = (options) => {
42
- const { extensions: userExtensions, router, mdx, explicitGraph, dependencies, ...baseConfig } = options ?? {};
20
+ const {
21
+ extensions: userExtensions,
22
+ router,
23
+ mdx,
24
+ explicitGraph,
25
+ dependencies,
26
+ runtimeModules,
27
+ ...baseConfig
28
+ } = options ?? {};
43
29
  const extensions = [...userExtensions ?? [".tsx"]];
44
30
  const mdxEnabled = mdx?.enabled ?? false;
45
31
  const mdxExtensions = mdx?.extensions ?? [".mdx"];
32
+ const resolvedRuntimeModules = resolveReactPluginRuntimeModules(runtimeModules);
46
33
  if (mdxEnabled) {
47
34
  appendMdxExtensions(extensions, mdxExtensions);
48
35
  } else if (mdx?.extensions?.length) {
@@ -52,10 +39,11 @@ const resolveReactPluginOptions = (options) => {
52
39
  }
53
40
  const rendererConfig = {
54
41
  routerAdapter: router,
42
+ runtimeModules: resolvedRuntimeModules,
55
43
  mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
56
44
  mdxExtensions,
57
- hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
58
- explicitGraphEnabled: explicitGraph ?? false
45
+ hmrPageMetadataCache: new HmrPageMetadataCache(),
46
+ forceBrowserGraph: explicitGraph ?? false
59
47
  };
60
48
  return {
61
49
  ...baseConfig,
@@ -74,11 +62,15 @@ class ReactPlugin extends IntegrationPlugin {
74
62
  runtimeBundleService;
75
63
  hmrPageMetadataCache;
76
64
  clientGraphBoundaryCache;
65
+ hmrStrategy;
77
66
  runtimeDependenciesInitialized = false;
78
67
  /**
79
- * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
68
+ * When true, always emit page browser graph / hydration assets.
69
+ *
70
+ * @remarks
71
+ * Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
80
72
  */
81
- explicitGraphEnabled;
73
+ forceBrowserGraph;
82
74
  rendererConfig;
83
75
  constructor(options) {
84
76
  const config = resolveReactPluginOptions(options);
@@ -94,20 +86,21 @@ class ReactPlugin extends IntegrationPlugin {
94
86
  this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
95
87
  this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
96
88
  this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
97
- this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
89
+ this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new HmrPageMetadataCache();
98
90
  this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
99
- this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
91
+ this.forceBrowserGraph = rendererConfig.forceBrowserGraph ?? false;
100
92
  this.rendererConfig = {
101
93
  ...rendererConfig,
102
94
  mdxExtensions: this.mdxExtensions,
103
95
  hmrPageMetadataCache: this.hmrPageMetadataCache,
104
- explicitGraphEnabled: this.explicitGraphEnabled
96
+ forceBrowserGraph: this.forceBrowserGraph
105
97
  };
106
98
  if (this.mdxEnabled) {
107
99
  appLogger.debug("MDX mode enabled with React jsx runtime");
108
100
  }
109
- this.runtimeBundleService = new ReactRuntimeBundleService({
110
- routerAdapter: this.routerAdapter
101
+ this.runtimeBundleService = new RuntimeBundleService({
102
+ routerAdapter: this.routerAdapter,
103
+ runtimeModules: this.rendererConfig.runtimeModules
111
104
  });
112
105
  }
113
106
  /**
@@ -129,9 +122,39 @@ class ReactPlugin extends IntegrationPlugin {
129
122
  return;
130
123
  }
131
124
  this.runtimeBundleService.setRootDir(this.appConfig?.rootDir);
125
+ this.runtimeBundleService.setWorkDir(
126
+ this.appConfig?.absolutePaths?.workDir ?? (this.appConfig?.rootDir ? path.join(this.appConfig.rootDir, this.appConfig.workDir ?? ".eco") : void 0)
127
+ );
128
+ this.runtimeBundleService.setRuntimeModules(this.resolveEffectiveRuntimeModules());
132
129
  this.integrationDependencies.unshift(...this.runtimeBundleService.getDependencies());
133
130
  this.runtimeDependenciesInitialized = true;
134
131
  }
132
+ resolveEffectiveRuntimeModules() {
133
+ const manualModules = this.rendererConfig.runtimeModules ?? [];
134
+ if (!this.routerAdapter || !this.appConfig) {
135
+ return manualModules;
136
+ }
137
+ const discovery = discoverLayoutRuntimeModuleSpecifiers({
138
+ searchDirs: [this.appConfig.absolutePaths.layoutsDir, this.appConfig.absolutePaths.componentsDir].filter(
139
+ Boolean
140
+ ),
141
+ projectRoot: this.appConfig.absolutePaths.projectDir,
142
+ routerImportPath: this.routerAdapter.bundle.importPath
143
+ });
144
+ const merged = mergeReactPluginRuntimeModules(manualModules, discovery.specifiers);
145
+ this.rendererConfig.runtimeModules = merged;
146
+ if (discovery.mode === "provider-scoped-fallback") {
147
+ appLogger.debug(
148
+ "Layout runtime auto-vendoring is using provider-scoped fallback discovery. Set runtimeProvider: true on provider root layouts to scope discovery explicitly."
149
+ );
150
+ }
151
+ if (discovery.specifiers.length > 0) {
152
+ appLogger.debug(
153
+ `Auto-vendoring layout runtime modules for persisted SPA layouts: ${discovery.specifiers.join(", ")}`
154
+ );
155
+ }
156
+ return merged;
157
+ }
135
158
  get plugins() {
136
159
  if (this.mdxLoaderPlugin) {
137
160
  return [this.mdxLoaderPlugin];
@@ -182,17 +205,18 @@ class ReactPlugin extends IntegrationPlugin {
182
205
  if (!this.hmrManager || !this.appConfig) {
183
206
  return void 0;
184
207
  }
185
- const context = this.hmrManager.getDefaultContext();
186
- return new ReactHmrStrategy({
187
- context,
188
- pageMetadataCache: this.hmrPageMetadataCache,
189
- runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
190
- mdxCompilerOptions: this.mdxCompilerOptions,
191
- ownedTemplateExtensions: this.extensions,
192
- allTemplateExtensions: this.appConfig.templatesExt,
193
- explicitGraphEnabled: this.explicitGraphEnabled,
194
- clientGraphBoundaryCache: this.clientGraphBoundaryCache
195
- });
208
+ if (!this.hmrStrategy) {
209
+ this.hmrStrategy = new ReactHmrStrategy({
210
+ context: this.hmrManager.getDefaultContext(),
211
+ pageMetadataCache: this.hmrPageMetadataCache,
212
+ runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
213
+ mdxCompilerOptions: this.mdxCompilerOptions,
214
+ ownedTemplateExtensions: this.extensions,
215
+ allTemplateExtensions: this.appConfig.templatesExt,
216
+ clientGraphBoundaryCache: this.clientGraphBoundaryCache
217
+ });
218
+ }
219
+ return this.hmrStrategy;
196
220
  }
197
221
  }
198
222
  function reactPlugin(options) {