@ecopages/react 0.2.0-beta.25 → 0.2.0-beta.27

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 (98) hide show
  1. package/README.md +17 -9
  2. package/package.json +42 -34
  3. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +7 -7
  4. package/src/{services/react-bundle.service.js → bundling/bundle.js} +9 -11
  5. package/src/{utils → bundling}/discover-layout-runtime-modules.js +2 -2
  6. package/src/{utils/react-runtime-alias-map.d.ts → bundling/runtime-alias-map.d.ts} +3 -3
  7. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +5 -5
  8. package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +4 -4
  9. package/src/bundling/runtime-mode.d.ts +9 -0
  10. package/src/bundling/runtime-mode.js +6 -0
  11. package/src/{utils/client-graph-ast-transform.d.ts → client-graph/ast-transform.d.ts} +1 -1
  12. package/src/{utils/client-graph-ast-transform.js → client-graph/ast-transform.js} +1 -1
  13. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
  14. package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
  15. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +1 -1
  16. package/src/{utils/client-graph-boundary-plugin.js → client-graph/boundary-plugin.js} +3 -3
  17. package/src/{utils/client-graph-reachability.d.ts → client-graph/specifier-classification.d.ts} +1 -1
  18. package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +3 -6
  19. package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +11 -20
  20. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  21. package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
  22. package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
  23. package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +45 -52
  24. package/src/{utils → hydration}/hydration-scripts.d.ts +33 -41
  25. package/src/hydration/hydration-scripts.js +353 -0
  26. package/src/{utils → hydration}/hydration-scripts.test.browser.js +6 -4
  27. package/src/hydration/page-data-manifest.d.ts +58 -0
  28. package/src/hydration/page-data-manifest.js +53 -0
  29. package/src/hydration/page-data-reader.d.ts +31 -0
  30. package/src/hydration/page-data-reader.js +64 -0
  31. package/src/hydration/page-payload.d.ts +67 -0
  32. package/src/hydration/page-payload.js +104 -0
  33. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  34. package/src/hydration/serialize-page-data-script.js +31 -0
  35. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
  36. package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +3 -3
  37. package/src/{services/react-page-module.service.d.ts → page/page-module.d.ts} +4 -7
  38. package/src/{services/react-page-module.service.js → page/page-module.js} +5 -9
  39. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +7 -3
  40. package/src/{react.plugin.js → plugin/react.plugin.js} +32 -30
  41. package/src/{react.types.d.ts → plugin/react.types.d.ts} +23 -8
  42. package/src/render/component-ownership.d.ts +50 -0
  43. package/src/render/component-ownership.js +23 -0
  44. package/src/render/component-ssr.d.ts +113 -0
  45. package/src/render/component-ssr.js +202 -0
  46. package/src/render/errors.d.ts +16 -0
  47. package/src/render/errors.js +18 -0
  48. package/src/{layout-compose.d.ts → render/layout-compose.d.ts} +8 -0
  49. package/src/{layout-compose.js → render/layout-compose.js} +14 -6
  50. package/src/render/react-renderer.d.ts +137 -0
  51. package/src/render/react-renderer.js +444 -0
  52. package/src/render/react-runtime.d.ts +13 -0
  53. package/src/render/react-runtime.js +21 -0
  54. package/src/render/unified-layout-composition.d.ts +53 -0
  55. package/src/render/unified-layout-composition.js +89 -0
  56. package/src/react-renderer.d.ts +0 -254
  57. package/src/react-renderer.js +0 -726
  58. package/src/serialize-page-data-script.d.ts +0 -8
  59. package/src/serialize-page-data-script.js +0 -10
  60. package/src/services/pages-index.d.ts +0 -64
  61. package/src/services/pages-index.js +0 -73
  62. package/src/services/react-page-payload.service.d.ts +0 -46
  63. package/src/services/react-page-payload.service.js +0 -67
  64. package/src/utils/hydration-scripts.js +0 -371
  65. /package/src/{utils → app}/client-only.d.ts +0 -0
  66. /package/src/{utils → app}/client-only.js +0 -0
  67. /package/src/{utils → app}/dynamic.d.ts +0 -0
  68. /package/src/{utils → app}/dynamic.js +0 -0
  69. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  70. /package/src/{utils → app}/dynamic.test.browser.js +0 -0
  71. /package/src/{utils → bundling}/discover-layout-runtime-modules.d.ts +0 -0
  72. /package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +0 -0
  73. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  74. /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
  75. /package/src/{utils/react-plugin-runtime-modules.d.ts → bundling/runtime-modules.d.ts} +0 -0
  76. /package/src/{utils/react-plugin-runtime-modules.js → bundling/runtime-modules.js} +0 -0
  77. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  78. /package/src/{utils → client-graph}/component-config-traversal.js +0 -0
  79. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  80. /package/src/{utils → client-graph}/declared-modules.js +0 -0
  81. /package/src/{utils → client-graph}/reachability-analyzer.d.ts +0 -0
  82. /package/src/{utils → client-graph}/reachability-analyzer.js +0 -0
  83. /package/src/{utils/client-graph-reachability.js → client-graph/specifier-classification.js} +0 -0
  84. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  85. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  86. /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
  87. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  88. /package/src/{utils → hmr}/hmr-scripts.js +0 -0
  89. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  90. /package/src/{utils/react-mdx-loader-plugin.d.ts → mdx/mdx-loader-plugin.d.ts} +0 -0
  91. /package/src/{utils/react-mdx-loader-plugin.js → mdx/mdx-loader-plugin.js} +0 -0
  92. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  93. /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
  94. /package/src/{react.types.js → plugin/react.types.js} +0 -0
  95. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  96. /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
  97. /package/src/{utils → render}/html-boundary.d.ts +0 -0
  98. /package/src/{utils → render}/html-boundary.js +0 -0
@@ -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,16 @@
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 { collectDeclaredModulesInConfig } from "../client-graph/declared-modules.js";
10
+ function getIslandComponentKey(componentFile, config) {
10
11
  return rapidhash(`${componentFile}:${config?.__eco?.id ?? ""}`).toString();
11
12
  }
12
- class ReactHydrationAssetService {
13
+ class HydrationAssetService {
13
14
  config;
14
15
  static ROUTER_PAGE_GROUPED_BUNDLE_ID = "ecopages-react-router-pages";
15
16
  constructor(config) {
@@ -27,11 +28,11 @@ class ReactHydrationAssetService {
27
28
  }
28
29
  /**
29
30
  * 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
31
  *
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
32
+ * @remarks
33
+ * When HMR is enabled, registers the source file as an HMR entrypoint and returns
34
+ * that URL. Otherwise returns the static resolved-assets path for the generated
35
+ * asset name.
35
36
  */
36
37
  async resolveAssetImportPath(pagePath, assetName) {
37
38
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
@@ -42,38 +43,40 @@ class ReactHydrationAssetService {
42
43
  }
43
44
  /**
44
45
  * 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
46
  */
54
- createPageDependencies(pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, isDevelopment, useBrowserRuntimeImports, isMdx) {
47
+ createPageDependencies(options) {
48
+ const {
49
+ pagePath,
50
+ componentName,
51
+ importPath,
52
+ pageModuleUrlExpression,
53
+ bundleOptions,
54
+ hmrEnabled,
55
+ useBrowserRuntimeImports,
56
+ isMdx
57
+ } = options;
55
58
  const runtimeImports = this.config.bundleService.getRuntimeImports();
56
59
  const groupedBundle = this.config.routerAdapter ? {
57
- id: ReactHydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
60
+ id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
58
61
  entryName: this.getRouterPageGroupedEntryName(pagePath)
59
62
  } : void 0;
60
63
  return [
61
64
  AssetFactory.createContentScript({
62
65
  position: "head",
63
66
  content: createHydrationScript({
64
- importPath: isDevelopment ? importPath : pagePath,
67
+ importPath: hmrEnabled ? importPath : pagePath,
65
68
  pageModuleUrlExpression,
66
69
  reactImportPath: useBrowserRuntimeImports ? runtimeImports.react : "react",
67
70
  reactDomClientImportPath: useBrowserRuntimeImports ? runtimeImports.reactDomClient : "react-dom/client",
68
71
  routerImportPath: useBrowserRuntimeImports ? runtimeImports.router : this.config.routerAdapter?.bundle.importPath,
69
- isDevelopment,
72
+ hmrEnabled,
70
73
  isMdx,
71
74
  router: this.config.routerAdapter,
72
75
  scriptId: componentName
73
76
  }),
74
77
  name: componentName,
75
78
  packageRole: "page-script",
76
- bundle: !isDevelopment,
79
+ bundle: !hmrEnabled,
77
80
  groupedBundle,
78
81
  bundleOptions,
79
82
  attributes: {
@@ -98,11 +101,11 @@ class ReactHydrationAssetService {
98
101
  */
99
102
  async buildComponentRenderAssets(componentFile, config) {
100
103
  const componentName = this.getIslandBundleName(componentFile);
101
- const componentKey = getReactIslandComponentKey(componentFile, config);
104
+ const componentKey = getIslandComponentKey(componentFile, config);
102
105
  const hydrationName = this.getIslandHydrationName(componentName, componentKey);
103
106
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
104
- const isDevelopment = hmrManager?.isEnabled() ?? false;
105
- if (isDevelopment) {
107
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
108
+ if (hmrEnabled) {
106
109
  this.config.hmrPageMetadataCache?.markOwnedEntrypoint(componentFile);
107
110
  }
108
111
  const importPath = await this.resolveAssetImportPath(componentFile, componentName);
@@ -138,7 +141,7 @@ class ReactHydrationAssetService {
138
141
  targetSelector: `[data-eco-component-key="${componentKey}"]`,
139
142
  componentRef: config?.__eco?.id,
140
143
  componentFile,
141
- isDevelopment
144
+ minify: !hmrEnabled
142
145
  }),
143
146
  name: hydrationName,
144
147
  packageRole: "keep-separate",
@@ -158,60 +161,50 @@ class ReactHydrationAssetService {
158
161
  return this.config.assetProcessingService.processDependencies(dependencies, componentName);
159
162
  }
160
163
  /**
161
- * Creates the Page Browser Graph dependency declarations for a React page.
164
+ * Creates the page browser graph dependency declarations for a React page.
165
+ *
166
+ * @remarks
167
+ * Chooses shared vendor import URLs when HMR is on, when running a non-production
168
+ * hosted runtime with HMR off, or when a router adapter is configured (router
169
+ * pages always externalize to shared runtimes). Production non-router pages
170
+ * may inline React into the page bundle instead.
162
171
  *
163
172
  * @param pagePath - Absolute file path of the page
164
173
  * @param isMdx - Whether the page is an MDX file
165
174
  * @param declaredModules - Explicitly declared browser module specifiers
166
- * @returns Declarative assets for core-owned processing
167
175
  */
168
176
  async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
169
177
  const componentName = `ecopages-react-${rapidhash(pagePath)}`;
170
178
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
171
- const isDevelopment = hmrManager?.isEnabled() ?? false;
172
- const isHostedDevelopment = !isDevelopment && process.env.NODE_ENV !== "production";
179
+ const hmrEnabled = hmrManager?.isEnabled() ?? false;
180
+ const productionRuntime = isReactProductionRuntime();
173
181
  const usesRouterRuntime = Boolean(this.config.routerAdapter);
174
- const useBrowserRuntimeImports = isDevelopment || isHostedDevelopment || usesRouterRuntime;
175
- if (isDevelopment) {
182
+ const useBrowserRuntimeImports = hmrEnabled || !productionRuntime || usesRouterRuntime;
183
+ if (hmrEnabled) {
176
184
  this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
177
185
  }
178
186
  const importPath = await this.resolveAssetImportPath(pagePath, componentName);
179
- const pageModuleUrlExpression = isDevelopment ? JSON.stringify(importPath) : "import.meta.url";
187
+ const pageModuleUrlExpression = hmrEnabled ? JSON.stringify(importPath) : "import.meta.url";
180
188
  const bundleOptions = await this.config.bundleService.createBundleOptions(
181
189
  componentName,
182
190
  isMdx,
183
191
  declaredModules,
184
192
  { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime }
185
193
  );
186
- const dependencies = this.createPageDependencies(
194
+ const dependencies = this.createPageDependencies({
187
195
  pagePath,
188
196
  componentName,
189
197
  importPath,
190
198
  pageModuleUrlExpression,
191
199
  bundleOptions,
192
- isDevelopment,
200
+ hmrEnabled,
193
201
  useBrowserRuntimeImports,
194
202
  isMdx
195
- );
203
+ });
196
204
  return dependencies;
197
205
  }
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
206
  }
214
207
  export {
215
- ReactHydrationAssetService,
216
- getReactIslandComponentKey
208
+ HydrationAssetService,
209
+ getIslandComponentKey
217
210
  };
@@ -3,7 +3,7 @@
3
3
  * These functions create the page entry modules that hydrate React routes.
4
4
  * @module
5
5
  */
6
- import type { ReactRouterAdapter } from '../router-adapter.js';
6
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
7
7
  /**
8
8
  * Options for generating a hydration script.
9
9
  */
@@ -20,14 +20,29 @@ export type HydrationScriptOptions = {
20
20
  reactDomClientImportPath: string;
21
21
  /** Direct import path for router runtime module */
22
22
  routerImportPath?: string;
23
- /** Whether running in development mode with HMR support */
24
- isDevelopment: boolean;
23
+ /**
24
+ * When true, emit HMR registration and hot-reload handlers.
25
+ *
26
+ * @remarks
27
+ * The asset layer uses the same flag to leave HMR entries unbundled. When
28
+ * false, this generator emits the same readable bootstrap without HMR hooks.
29
+ */
30
+ hmrEnabled: boolean;
25
31
  /** Whether the source file is an MDX file */
26
32
  isMdx: boolean;
27
33
  /** Optional router adapter for SPA navigation */
28
34
  router?: ReactRouterAdapter;
29
35
  /** Import path for shared layout composition helper */
30
36
  layoutComposeImportPath?: string;
37
+ /**
38
+ * Optional import path for the page-data reader.
39
+ *
40
+ * @remarks
41
+ * When omitted, hydration scripts inline the reader so native browser ESM /
42
+ * HMR entry evaluation does not depend on bare `@ecopages/react/*` imports.
43
+ * Browser unit tests that execute `data:` scripts may still pass a resolvable URL.
44
+ */
45
+ pageDataReaderImportPath?: string;
31
46
  };
32
47
  export type IslandHydrationScriptOptions = {
33
48
  /** Bundled browser module path for the island component. */
@@ -44,51 +59,28 @@ export type IslandHydrationScriptOptions = {
44
59
  componentRef?: string;
45
60
  /** Optional source file hint used as fallback for component resolution. */
46
61
  componentFile?: string;
47
- /** Enables development-oriented non-minified output. */
48
- isDevelopment: boolean;
62
+ /**
63
+ * When true, emit a compact source string.
64
+ *
65
+ * @remarks
66
+ * Island bootstraps use `bundle: false`, so compact output must be generated
67
+ * here rather than delegated to the bundler.
68
+ */
69
+ minify: boolean;
49
70
  };
50
71
  /**
51
- * Creates a hydration script for client-side React hydration.
72
+ * Creates a page hydration entry module.
52
73
  *
53
- * Why this dispatcher exists:
54
- * the runtime matrix is small but behaviorally different across development vs
55
- * production and router vs non-router pages. Keeping that branch here preserves
56
- * a compact public API while allowing each emitted script to stay focused.
57
- *
58
- * Selection rules:
59
- * - development uses readable scripts with HMR hooks
60
- * - production uses minified equivalents
61
- * - router presence decides whether page updates flow through the router runtime
62
- * or rebuild directly from the page module
63
- *
64
- * @param options - Configuration options for script generation
65
- * @returns The generated hydration script as a string
74
+ * @remarks
75
+ * Always emits readable source. Production page assets set `bundle: true` so
76
+ * core's content-script processor minifies the result. Do not hand-minify here.
66
77
  */
67
78
  export declare function createHydrationScript(options: HydrationScriptOptions): string;
68
79
  /**
69
80
  * Creates the client bootstrap for component-level React islands.
70
81
  *
71
- * The island runtime intentionally uses `createRoot()` (not `hydrateRoot()`) and
72
- * mounts into the SSR element identified by `targetSelector`.
73
- *
74
- * Rationale:
75
- * - No synthetic wrapper element is introduced in SSR output.
76
- * - DOM structure remains identical to authored component markup.
77
- * - Runtime ownership is isolated per island instance.
78
- *
79
- * Generated script behavior:
80
- * - resolves the component export by metadata (`componentRef`, `componentFile`)
81
- * before falling back to default/first function export
82
- * - selects island root using `targetSelector`
83
- * - replaces the SSR host with a dedicated client-owned container
84
- * - creates a fresh React root and renders with serialized `props`
85
- *
86
- * Why it remounts instead of hydrating:
87
- * island SSR intentionally avoids synthetic wrapper elements. The runtime swaps
88
- * the authored SSR node for a dedicated client-owned container before mounting
89
- * so the server markup stays clean while the client still gets a stable root.
90
- *
91
- * @param options Island script generation options.
92
- * @returns Browser-executable JavaScript module source.
82
+ * @remarks
83
+ * Island scripts use `bundle: false`, so compact output still needs a
84
+ * handwritten string.
93
85
  */
94
86
  export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;