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

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,25 @@
1
+ /**
2
+ * Resolves browser import paths for React page hydration bootstraps.
3
+ *
4
+ * @remarks
5
+ * When `useBrowserRuntimeImports` is true, helpers and runtimes resolve to shared
6
+ * `/assets/vendors/*.js` URLs so unbundled HMR bootstraps evaluate as native ESM.
7
+ * When false, bare package names are emitted for the production page bundler.
8
+ */
9
+ import type { ReactRuntimeImports } from '../bundling/runtime-bundle.js';
10
+ export type HydrationBootstrapImportPaths = {
11
+ reactImportPath: string;
12
+ reactDomClientImportPath: string;
13
+ routerImportPath?: string;
14
+ layoutComposeImportPath: string;
15
+ pageLayoutNormalizationImportPath: string;
16
+ };
17
+ export type ResolveHydrationBootstrapImportsOptions = {
18
+ useBrowserRuntimeImports: boolean;
19
+ runtimeImports: ReactRuntimeImports;
20
+ routerAdapterImportPath?: string;
21
+ };
22
+ /**
23
+ * Returns import paths for React page hydration scripts.
24
+ */
25
+ export declare function resolveHydrationBootstrapImports(options: ResolveHydrationBootstrapImportsOptions): HydrationBootstrapImportPaths;
@@ -0,0 +1,23 @@
1
+ import { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from "../bundling/bootstrap-package-paths.js";
2
+ function resolveHydrationBootstrapImports(options) {
3
+ const { useBrowserRuntimeImports, runtimeImports, routerAdapterImportPath } = options;
4
+ if (useBrowserRuntimeImports) {
5
+ return {
6
+ reactImportPath: runtimeImports.react,
7
+ reactDomClientImportPath: runtimeImports.reactDomClient,
8
+ ...runtimeImports.router || routerAdapterImportPath ? { routerImportPath: runtimeImports.router ?? routerAdapterImportPath } : {},
9
+ layoutComposeImportPath: runtimeImports.layoutCompose,
10
+ pageLayoutNormalizationImportPath: runtimeImports.pageLayoutNormalization
11
+ };
12
+ }
13
+ return {
14
+ reactImportPath: "react",
15
+ reactDomClientImportPath: "react-dom/client",
16
+ ...routerAdapterImportPath ? { routerImportPath: routerAdapterImportPath } : {},
17
+ layoutComposeImportPath: LAYOUT_COMPOSE_PACKAGE,
18
+ pageLayoutNormalizationImportPath: PAGE_LAYOUT_NORMALIZATION_PACKAGE
19
+ };
20
+ }
21
+ export {
22
+ resolveHydrationBootstrapImports
23
+ };
@@ -9,51 +9,53 @@
9
9
  import type { EcoComponentConfig } from '@ecopages/core';
10
10
  import { type AssetDefinition, type ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
11
11
  import type { AssetProcessingService } from '@ecopages/core/services/asset-processing-service';
12
- import type { ReactBundleService } from './react-bundle.service.js';
13
- import type { ReactHmrPageMetadataCache } from './react-hmr-page-metadata-cache.js';
14
- import type { ReactRouterAdapter } from '../router-adapter.js';
12
+ import type { BundleService } from '../bundling/bundle.js';
13
+ import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
14
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
15
15
  /**
16
- * Configuration for the ReactHydrationAssetService.
16
+ * Configuration for the HydrationAssetService.
17
17
  */
18
- export interface ReactHydrationAssetServiceConfig {
18
+ export interface HydrationAssetServiceConfig {
19
19
  srcDir: string;
20
20
  routerAdapter?: ReactRouterAdapter;
21
21
  assetProcessingService: AssetProcessingService;
22
- bundleService: ReactBundleService;
23
- hmrPageMetadataCache?: ReactHmrPageMetadataCache;
22
+ bundleService: BundleService;
23
+ hmrPageMetadataCache?: HmrPageMetadataCache;
24
24
  }
25
- export declare function getReactIslandComponentKey(componentFile: string, config?: EcoComponentConfig): string;
25
+ type PageDependencyOptions = {
26
+ pagePath: string;
27
+ componentName: string;
28
+ importPath: string;
29
+ pageModuleUrlExpression: string;
30
+ bundleOptions: Record<string, unknown>;
31
+ hmrEnabled: boolean;
32
+ useBrowserRuntimeImports: boolean;
33
+ isMdx: boolean;
34
+ };
35
+ export declare function getIslandComponentKey(componentFile: string, config?: EcoComponentConfig): string;
26
36
  /**
27
37
  * Manages the creation of client-side hydration assets for React pages and component islands.
28
38
  */
29
- export declare class ReactHydrationAssetService {
39
+ export declare class HydrationAssetService {
30
40
  private readonly config;
31
41
  private static readonly ROUTER_PAGE_GROUPED_BUNDLE_ID;
32
- constructor(config: ReactHydrationAssetServiceConfig);
42
+ constructor(config: HydrationAssetServiceConfig);
33
43
  private getIslandBundleName;
34
44
  private getIslandHydrationName;
35
45
  private getRouterPageGroupedEntryName;
36
46
  /**
37
47
  * Resolves the browser import path used for a React-owned page or island module.
38
- * Uses HMR manager for development or constructs static path for production.
39
48
  *
40
- * @param pagePath - Absolute path to the page source file
41
- * @param assetName - Generated asset name
42
- * @returns The resolved browser import path for the module
49
+ * @remarks
50
+ * When HMR is enabled, registers the source file as an HMR entrypoint and returns
51
+ * that URL. Otherwise returns the static resolved-assets path for the generated
52
+ * asset name.
43
53
  */
44
54
  resolveAssetImportPath(pagePath: string, assetName: string): Promise<string>;
45
55
  /**
46
56
  * Creates the page-owned route entry asset for hydration and client navigation.
47
- *
48
- * @param pagePath - Absolute path to the page source file
49
- * @param componentName - Generated unique component name
50
- * @param importPath - Resolved browser import path used by development HMR
51
- * @param bundleOptions - Bundle configuration options
52
- * @param isDevelopment - Whether running in development mode with HMR
53
- * @param isMdx - Whether the source file is an MDX file
54
- * @returns One page-owned asset definition for processing
55
57
  */
56
- createPageDependencies(pagePath: string, componentName: string, importPath: string, pageModuleUrlExpression: string, bundleOptions: Record<string, unknown>, isDevelopment: boolean, useBrowserRuntimeImports: boolean, isMdx: boolean): AssetDefinition[];
58
+ createPageDependencies(options: PageDependencyOptions): AssetDefinition[];
57
59
  /**
58
60
  * Builds client-side assets for a React component island.
59
61
  *
@@ -65,20 +67,18 @@ export declare class ReactHydrationAssetService {
65
67
  */
66
68
  buildComponentRenderAssets(componentFile: string, config?: EcoComponentConfig): Promise<ProcessedAsset[]>;
67
69
  /**
68
- * Creates the Page Browser Graph dependency declarations for a React page.
70
+ * Creates the page browser graph dependency declarations for a React page.
71
+ *
72
+ * @remarks
73
+ * Chooses shared vendor import URLs when HMR is on, when running a non-production
74
+ * hosted runtime with HMR off, or when a router adapter is configured (router
75
+ * pages always externalize to shared runtimes). Production non-router pages
76
+ * may inline React into the page bundle instead.
69
77
  *
70
78
  * @param pagePath - Absolute file path of the page
71
79
  * @param isMdx - Whether the page is an MDX file
72
80
  * @param declaredModules - Explicitly declared browser module specifiers
73
- * @returns Declarative assets for core-owned processing
74
81
  */
75
82
  createPageBrowserGraphDependencies(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<AssetDefinition[]>;
76
- /**
77
- * Builds the Page Browser Graph assets for a React page.
78
- *
79
- * @remarks
80
- * Kept as a compatibility wrapper while callers migrate to core-owned page
81
- * graph assembly.
82
- */
83
- buildPageBrowserGraphAssets(pagePath: string, isMdx: boolean, declaredModules: string[]): Promise<ProcessedAsset[]>;
84
83
  }
84
+ export {};
@@ -1,15 +1,17 @@
1
1
  import path from "node:path";
2
2
  import { rapidhash } from "@ecopages/core/hash";
3
3
  import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
4
+ import { isReactProductionRuntime } from "../bundling/runtime-mode.js";
4
5
  import {
5
6
  AssetFactory
6
7
  } from "@ecopages/core/services/asset-processing-service";
7
- import { createHydrationScript, createIslandHydrationScript } from "../utils/hydration-scripts.js";
8
- import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
9
- function getReactIslandComponentKey(componentFile, config) {
8
+ import { createHydrationScript, createIslandHydrationScript } from "./hydration-scripts.js";
9
+ import { resolveHydrationBootstrapImports } from "./bootstrap-imports.js";
10
+ import { collectDeclaredModulesInConfig } from "../client-graph/declared-modules.js";
11
+ function getIslandComponentKey(componentFile, config) {
10
12
  return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
11
13
  }
12
- class ReactHydrationAssetService {
14
+ class HydrationAssetService {
13
15
  config;
14
16
  static ROUTER_PAGE_GROUPED_BUNDLE_ID = "ecopages-react-router-pages";
15
17
  constructor(config) {
@@ -27,11 +29,11 @@ class ReactHydrationAssetService {
27
29
  }
28
30
  /**
29
31
  * Resolves the browser import path used for a React-owned page or island module.
30
- * Uses HMR manager for development or constructs static path for production.
31
32
  *
32
- * @param pagePath - Absolute path to the page source file
33
- * @param assetName - Generated asset name
34
- * @returns The resolved browser import path for the module
33
+ * @remarks
34
+ * When HMR is enabled, registers the source file as an HMR entrypoint and returns
35
+ * that URL. Otherwise returns the static resolved-assets path for the generated
36
+ * asset name.
35
37
  */
36
38
  async resolveAssetImportPath(pagePath, assetName) {
37
39
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
@@ -42,38 +44,53 @@ class ReactHydrationAssetService {
42
44
  }
43
45
  /**
44
46
  * Creates the page-owned route entry asset for hydration and client navigation.
45
- *
46
- * @param pagePath - Absolute path to the page source file
47
- * @param componentName - Generated unique component name
48
- * @param importPath - Resolved browser import path used by development HMR
49
- * @param bundleOptions - Bundle configuration options
50
- * @param isDevelopment - Whether running in development mode with HMR
51
- * @param isMdx - Whether the source file is an MDX file
52
- * @returns One page-owned asset definition for processing
53
47
  */
54
- createPageDependencies(pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, isDevelopment, useBrowserRuntimeImports, isMdx) {
48
+ createPageDependencies(options) {
49
+ const {
50
+ pagePath,
51
+ componentName,
52
+ importPath,
53
+ pageModuleUrlExpression,
54
+ bundleOptions,
55
+ hmrEnabled,
56
+ useBrowserRuntimeImports,
57
+ isMdx
58
+ } = options;
55
59
  const runtimeImports = this.config.bundleService.getRuntimeImports();
56
- const groupedBundle = this.config.routerAdapter ? {
57
- id: ReactHydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
60
+ const groupedBundle = !hmrEnabled && this.config.routerAdapter ? {
61
+ id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
58
62
  entryName: this.getRouterPageGroupedEntryName(pagePath)
59
63
  } : void 0;
64
+ const bootstrapImports = resolveHydrationBootstrapImports({
65
+ useBrowserRuntimeImports,
66
+ runtimeImports,
67
+ routerAdapterImportPath: this.config.routerAdapter?.bundle.importPath
68
+ });
60
69
  return [
61
70
  AssetFactory.createContentScript({
62
71
  position: "head",
63
72
  content: createHydrationScript({
64
- importPath: isDevelopment ? importPath : pagePath,
73
+ importPath: hmrEnabled ? importPath : pagePath,
65
74
  pageModuleUrlExpression,
66
- reactImportPath: useBrowserRuntimeImports ? runtimeImports.react : "react",
67
- reactDomClientImportPath: useBrowserRuntimeImports ? runtimeImports.reactDomClient : "react-dom/client",
68
- routerImportPath: useBrowserRuntimeImports ? runtimeImports.router : this.config.routerAdapter?.bundle.importPath,
69
- isDevelopment,
75
+ reactImportPath: bootstrapImports.reactImportPath,
76
+ reactDomClientImportPath: bootstrapImports.reactDomClientImportPath,
77
+ routerImportPath: bootstrapImports.routerImportPath,
78
+ layoutComposeImportPath: bootstrapImports.layoutComposeImportPath,
79
+ pageLayoutNormalizationImportPath: bootstrapImports.pageLayoutNormalizationImportPath,
80
+ hmrEnabled,
70
81
  isMdx,
71
82
  router: this.config.routerAdapter,
72
83
  scriptId: componentName
73
84
  }),
74
85
  name: componentName,
75
86
  packageRole: "page-script",
76
- bundle: !isDevelopment,
87
+ /**
88
+ * @remarks
89
+ * HMR bootstraps stay unbundled write-through ESM. Helper imports must
90
+ * already be browser-resolvable vendor URLs from
91
+ * {@link resolveHydrationBootstrapImports}.
92
+ */
93
+ bundle: !hmrEnabled,
77
94
  groupedBundle,
78
95
  bundleOptions,
79
96
  attributes: {
@@ -98,11 +115,11 @@ class ReactHydrationAssetService {
98
115
  */
99
116
  async buildComponentRenderAssets(componentFile, config) {
100
117
  const componentName = this.getIslandBundleName(componentFile);
101
- const componentKey = getReactIslandComponentKey(componentFile, config);
118
+ const componentKey = getIslandComponentKey(componentFile, config);
102
119
  const hydrationName = this.getIslandHydrationName(componentName, componentKey);
103
120
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
104
- const isDevelopment = hmrManager?.isEnabled() ?? false;
105
- if (isDevelopment) {
121
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
122
+ if (hmrEnabled) {
106
123
  this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
107
124
  }
108
125
  const importPath = await this.resolveAssetImportPath(componentFile, componentName);
@@ -138,7 +155,7 @@ class ReactHydrationAssetService {
138
155
  targetSelector: `[data-eco-component-key="${componentKey}"]`,
139
156
  componentRef: config?.__eco?.id,
140
157
  componentFile,
141
- isDevelopment
158
+ minify: !hmrEnabled
142
159
  }),
143
160
  name: hydrationName,
144
161
  packageRole: "keep-separate",
@@ -158,60 +175,50 @@ class ReactHydrationAssetService {
158
175
  return this.config.assetProcessingService.processDependencies(dependencies, componentName);
159
176
  }
160
177
  /**
161
- * Creates the Page Browser Graph dependency declarations for a React page.
178
+ * Creates the page browser graph dependency declarations for a React page.
179
+ *
180
+ * @remarks
181
+ * Chooses shared vendor import URLs when HMR is on, when running a non-production
182
+ * hosted runtime with HMR off, or when a router adapter is configured (router
183
+ * pages always externalize to shared runtimes). Production non-router pages
184
+ * may inline React into the page bundle instead.
162
185
  *
163
186
  * @param pagePath - Absolute file path of the page
164
187
  * @param isMdx - Whether the page is an MDX file
165
188
  * @param declaredModules - Explicitly declared browser module specifiers
166
- * @returns Declarative assets for core-owned processing
167
189
  */
168
190
  async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
169
191
  const componentName = `ecopages-react-${rapidhash(pagePath)}`;
170
192
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
171
- const isDevelopment = hmrManager?.isEnabled() ?? false;
172
- const isHostedDevelopment = !isDevelopment && process.env.NODE_ENV !== "production";
193
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
194
+ const productionRuntime = isReactProductionRuntime();
173
195
  const usesRouterRuntime = Boolean(this.config.routerAdapter);
174
- const useBrowserRuntimeImports = isDevelopment || isHostedDevelopment || usesRouterRuntime;
175
- if (isDevelopment) {
196
+ const useBrowserRuntimeImports = hmrEnabled || !productionRuntime || usesRouterRuntime;
197
+ if (hmrEnabled) {
176
198
  this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
177
199
  }
178
200
  const importPath = await this.resolveAssetImportPath(pagePath, componentName);
179
- const pageModuleUrlExpression = isDevelopment ? JSON.stringify(importPath) : "import.meta.url";
201
+ const pageModuleUrlExpression = hmrEnabled ? JSON.stringify(importPath) : "import.meta.url";
180
202
  const bundleOptions = await this.config.bundleService.createBundleOptions(
181
203
  componentName,
182
204
  isMdx,
183
205
  declaredModules,
184
206
  { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime }
185
207
  );
186
- const dependencies = this.createPageDependencies(
208
+ const dependencies = this.createPageDependencies({
187
209
  pagePath,
188
210
  componentName,
189
211
  importPath,
190
212
  pageModuleUrlExpression,
191
213
  bundleOptions,
192
- isDevelopment,
214
+ hmrEnabled,
193
215
  useBrowserRuntimeImports,
194
216
  isMdx
195
- );
217
+ });
196
218
  return dependencies;
197
219
  }
198
- /**
199
- * Builds the Page Browser Graph assets for a React page.
200
- *
201
- * @remarks
202
- * Kept as a compatibility wrapper while callers migrate to core-owned page
203
- * graph assembly.
204
- */
205
- async buildPageBrowserGraphAssets(pagePath, isMdx, declaredModules) {
206
- const componentName = `ecopages-react-${rapidhash(pagePath)}`;
207
- const dependencies = await this.createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules);
208
- if (!this.config.assetProcessingService) {
209
- throw new Error("AssetProcessingService is not set");
210
- }
211
- return this.config.assetProcessingService.processDependencies(dependencies, componentName);
212
- }
213
220
  }
214
221
  export {
215
- ReactHydrationAssetService,
216
- getReactIslandComponentKey
222
+ HydrationAssetService,
223
+ getIslandComponentKey
217
224
  };
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Hydration script generators for React pages.
3
+ * These functions create the page entry modules that hydrate React routes.
4
+ * @module
5
+ */
6
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
7
+ /**
8
+ * Options for generating a hydration script.
9
+ */
10
+ export type HydrationScriptOptions = {
11
+ /** The module path imported by the page entry module. */
12
+ importPath: string;
13
+ /** Browser expression that resolves to the page module URL the router should import. */
14
+ pageModuleUrlExpression?: string;
15
+ /** Stable id of the page entry script tag in the document. */
16
+ scriptId: string;
17
+ /** Direct import path for React runtime module */
18
+ reactImportPath: string;
19
+ /** Direct import path for react-dom/client runtime module */
20
+ reactDomClientImportPath: string;
21
+ /** Direct import path for router runtime module */
22
+ routerImportPath?: string;
23
+ /**
24
+ * When true, emit HMR registration and hot-reload handlers.
25
+ *
26
+ * @remarks
27
+ * HMR page bootstraps stay unbundled and evaluate as native browser ESM.
28
+ * Callers must supply browser-resolvable import paths (shared vendor URLs)
29
+ * so generated source does not emit bare `@ecopages/*` imports. When false,
30
+ * this generator emits the same readable bootstrap without HMR hooks.
31
+ */
32
+ hmrEnabled: boolean;
33
+ /** Whether the source file is an MDX file */
34
+ isMdx: boolean;
35
+ /** Optional router adapter for SPA navigation */
36
+ router?: ReactRouterAdapter;
37
+ /**
38
+ * Import path for shared layout composition helper.
39
+ *
40
+ * @remarks
41
+ * Required so callers (not this generator) decide vendor URL vs bare package.
42
+ */
43
+ layoutComposeImportPath: string;
44
+ /**
45
+ * Import path for MDX page layout normalization helper.
46
+ *
47
+ * @remarks
48
+ * Required so callers (not this generator) decide vendor URL vs bare package.
49
+ */
50
+ pageLayoutNormalizationImportPath: string;
51
+ /**
52
+ * Optional import path for the page-data reader.
53
+ *
54
+ * @remarks
55
+ * When omitted, hydration scripts inline the reader so native browser ESM /
56
+ * HMR entry evaluation does not depend on bare `@ecopages/react/*` imports.
57
+ * Browser unit tests that execute `data:` scripts may still pass a resolvable URL.
58
+ */
59
+ pageDataReaderImportPath?: string;
60
+ };
61
+ export type IslandHydrationScriptOptions = {
62
+ /** Bundled browser module path for the island component. */
63
+ importPath: string;
64
+ /** Stable id of the island bootstrap script tag in the document. */
65
+ scriptId: string;
66
+ /** Browser import path for React runtime. */
67
+ reactImportPath: string;
68
+ /** Browser import path for react-dom/client runtime. */
69
+ reactDomClientImportPath: string;
70
+ /** Selector that resolves to all SSR root elements for this island component. */
71
+ targetSelector: string;
72
+ /** Optional stable component id used to resolve named exports reliably. */
73
+ componentRef?: string;
74
+ /** Optional source file hint used as fallback for component resolution. */
75
+ componentFile?: string;
76
+ /**
77
+ * When true, emit a compact source string.
78
+ *
79
+ * @remarks
80
+ * Island bootstraps use `bundle: false`, so compact output must be generated
81
+ * here rather than delegated to the bundler.
82
+ */
83
+ minify: boolean;
84
+ };
85
+ /**
86
+ * Creates a page hydration entry module.
87
+ *
88
+ * @remarks
89
+ * Always emits readable source. Production page assets set `bundle: true` so
90
+ * core's content-script processor minifies the result. Do not hand-minify here.
91
+ */
92
+ export declare function createHydrationScript(options: HydrationScriptOptions): string;
93
+ /**
94
+ * Creates the client bootstrap for component-level React islands.
95
+ *
96
+ * @remarks
97
+ * Island scripts use `bundle: false`, so compact output still needs a
98
+ * handwritten string.
99
+ */
100
+ export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;