@ecopages/react 0.6.1 → 0.7.1

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 (95) hide show
  1. package/README.md +50 -87
  2. package/package.json +32 -14
  3. package/src/bundling/bootstrap-package-paths.d.ts +13 -1
  4. package/src/bundling/bootstrap-package-paths.js +25 -3
  5. package/src/bundling/bundle.d.ts +8 -36
  6. package/src/bundling/bundle.js +42 -73
  7. package/src/client-graph/ast-transform-eco-page.d.ts +10 -6
  8. package/src/client-graph/ast-transform-eco-page.js +56 -35
  9. package/src/client-graph/ast-transform-import-edits.d.ts +10 -2
  10. package/src/client-graph/ast-transform-import-edits.js +36 -6
  11. package/src/client-graph/ast-transform-stripped-imports.d.ts +37 -0
  12. package/src/client-graph/ast-transform-stripped-imports.js +191 -0
  13. package/src/client-graph/ast-transform-walk-imports.d.ts +4 -0
  14. package/src/client-graph/ast-transform-walk-imports.js +15 -1
  15. package/src/client-graph/ast-transform.d.ts +12 -3
  16. package/src/client-graph/ast-transform.js +41 -56
  17. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +3 -0
  18. package/src/client-graph/boundary-plugin-read-file-inline.js +14 -10
  19. package/src/client-graph/boundary-plugin-transform.d.ts +5 -4
  20. package/src/client-graph/boundary-plugin-transform.js +6 -13
  21. package/src/client-graph/boundary-plugin.d.ts +47 -1
  22. package/src/client-graph/boundary-plugin.js +267 -53
  23. package/src/client-graph/foreign-boundary-rewrite.d.ts +31 -0
  24. package/src/client-graph/foreign-boundary-rewrite.js +360 -0
  25. package/src/client-graph/foreign-jsx-reach.d.ts +25 -0
  26. package/src/client-graph/foreign-jsx-reach.js +68 -0
  27. package/src/client-graph/module-classification.js +3 -10
  28. package/src/client-graph/reachability-traverse.js +35 -105
  29. package/src/client-graph/requested-exports-plan.d.ts +62 -0
  30. package/src/client-graph/requested-exports-plan.js +125 -0
  31. package/src/client-graph/scope-walk.d.ts +37 -0
  32. package/src/client-graph/scope-walk.js +407 -0
  33. package/src/client-graph/specifier-classification.d.ts +2 -1
  34. package/src/client-graph/specifier-classification.js +9 -7
  35. package/src/contracts/router-adapter.d.ts +9 -24
  36. package/src/dev-transform/react-dev-transform-contributor.d.ts +4 -4
  37. package/src/dev-transform/react-dev-transform-contributor.js +6 -7
  38. package/src/hmr/hmr-strategy-process.d.ts +7 -5
  39. package/src/hmr/hmr-strategy-process.js +21 -16
  40. package/src/hmr/hmr-strategy.d.ts +11 -10
  41. package/src/hmr/hmr-strategy.js +32 -53
  42. package/src/hmr/page-metadata-cache.js +1 -1
  43. package/src/hydration/browser/foreign-boundary.d.ts +29 -0
  44. package/src/hydration/browser/foreign-boundary.js +128 -0
  45. package/src/hydration/browser/island-hydration.d.ts +3 -4
  46. package/src/hydration/browser/island-hydration.js +3 -4
  47. package/src/hydration/browser/page-hydration-hmr.d.ts +8 -7
  48. package/src/hydration/browser/page-hydration-hmr.js +53 -10
  49. package/src/hydration/browser/page-hydration.d.ts +6 -5
  50. package/src/hydration/browser/page-hydration.js +8 -6
  51. package/src/hydration/foreign-subtree.d.ts +27 -0
  52. package/src/hydration/foreign-subtree.js +69 -0
  53. package/src/hydration/hydration-asset.d.ts +37 -29
  54. package/src/hydration/hydration-asset.js +74 -138
  55. package/src/hydration/hydration-island-entry-source.d.ts +17 -0
  56. package/src/hydration/hydration-island-entry-source.js +32 -0
  57. package/src/hydration/hydration-page-entry-source.d.ts +20 -2
  58. package/src/hydration/hydration-page-entry-source.js +17 -12
  59. package/src/hydration/page-data-reader.d.ts +4 -7
  60. package/src/hydration/page-data-reader.js +5 -10
  61. package/src/mdx/mdx-config-dependency.d.ts +10 -15
  62. package/src/mdx/mdx-config-dependency.js +9 -22
  63. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  64. package/src/mdx/mdx-loader-plugin.js +1 -0
  65. package/src/page/page-module.js +1 -1
  66. package/src/plugin/react.plugin.d.ts +0 -7
  67. package/src/plugin/react.plugin.js +4 -33
  68. package/src/plugin/react.types.d.ts +0 -29
  69. package/src/render/component-ssr.d.ts +18 -0
  70. package/src/render/component-ssr.js +37 -0
  71. package/src/render/layout-compose.d.ts +4 -2
  72. package/src/render/layout-compose.js +13 -6
  73. package/src/render/layout-render-tracker.d.ts +20 -0
  74. package/src/render/layout-render-tracker.js +33 -0
  75. package/src/render/react-renderer.d.ts +28 -10
  76. package/src/render/react-renderer.js +103 -38
  77. package/src/render/react-runtime.js +2 -2
  78. package/src/bundling/runtime-alias-map.d.ts +0 -12
  79. package/src/bundling/runtime-alias-map.js +0 -110
  80. package/src/bundling/runtime-bundle.d.ts +0 -70
  81. package/src/bundling/runtime-bundle.js +0 -233
  82. package/src/bundling/runtime-interop-plugin.d.ts +0 -5
  83. package/src/bundling/runtime-interop-plugin.js +0 -32
  84. package/src/bundling/runtime-mode.d.ts +0 -1
  85. package/src/bundling/runtime-mode.js +0 -10
  86. package/src/bundling/runtime-modules.d.ts +0 -21
  87. package/src/bundling/runtime-modules.js +0 -28
  88. package/src/hydration/bootstrap-imports.d.ts +0 -25
  89. package/src/hydration/bootstrap-imports.js +0 -33
  90. package/src/hydration/compiled-page-hydration-options.d.ts +0 -19
  91. package/src/hydration/compiled-page-hydration-options.js +0 -1
  92. package/src/hydration/hydration-script-compiler.d.ts +0 -47
  93. package/src/hydration/hydration-script-compiler.js +0 -213
  94. package/src/runtime/use-sync-external-store-with-selector.d.ts +0 -3
  95. package/src/runtime/use-sync-external-store-with-selector.js +0 -54
@@ -6,13 +6,11 @@
6
6
  *
7
7
  * @module
8
8
  */
9
- import path from 'node:path';
10
- import { contentHash } from '@ecopages/core/build';
11
- import { RESOLVED_ASSETS_DIR } from '@ecopages/core/build';
12
- import { isReactProductionRuntime } from '../bundling/runtime-mode.js';
13
- import { APP_BROWSER_CLIENT_BUNDLE_ID, AssetFactory, createAppBrowserClientEntry, } from '@ecopages/core/integration';
14
- import { IslandHydrationScriptCompiler, PageHydrationScriptCompiler } from './hydration-script-compiler.js';
15
- import { resolveHydrationBootstrapImports } from './bootstrap-imports.js';
9
+ import { path } from '@ecopages/file-system/path';
10
+ import { contentHash, RESOLVED_ASSETS_DIR, toRootRelativePath } from '@ecopages/core/build';
11
+ import { APP_BROWSER_CLIENT_BUNDLE_ID, AssetFactory, } from '@ecopages/core/integration';
12
+ import { createIslandEntrySource } from './hydration-island-entry-source.js';
13
+ import { createPageEntrySource } from './hydration-page-entry-source.js';
16
14
  import { collectDeclaredModulesInConfig } from '../client-graph/declared-modules.js';
17
15
  /**
18
16
  * Derives the stable component key used by asset grouping and host selectors.
@@ -22,35 +20,38 @@ import { collectDeclaredModulesInConfig } from '../client-graph/declared-modules
22
20
  * separate component ID, so repeated uses share browser assets without sharing
23
21
  * a React root.
24
22
  *
25
- * @param componentFile - Absolute source path of the React component.
23
+ * @param sourceKey - Source path of the React component relative to the app root (`toRootRelativePath`).
26
24
  * @param config - Optional component identity used to distinguish entries.
27
25
  * @returns Stable key used in selectors and asset names.
28
26
  */
29
- export function getIslandComponentKey(componentFile, config) {
30
- return BigInt(`0x${contentHash(`${componentFile}:${config?.identity?.id ?? ''}`, 16)}`).toString(10);
27
+ export function getIslandComponentKey(sourceKey, config) {
28
+ return BigInt(`0x${contentHash(`${sourceKey}:${config?.identity?.id ?? ''}`, 16)}`).toString(10);
31
29
  }
32
30
  /**
33
31
  * Manages the creation of client-side hydration assets for React pages and component islands.
34
32
  */
35
33
  export class HydrationAssetService {
36
34
  config;
37
- islandScriptCompiler = new IslandHydrationScriptCompiler();
38
- pageScriptCompiler = new PageHydrationScriptCompiler();
39
- static ROUTER_PAGE_GROUPED_BUNDLE_ID = APP_BROWSER_CLIENT_BUNDLE_ID;
40
35
  constructor(config) {
41
36
  this.config = config;
42
37
  }
38
+ toSourceKey(filePath) {
39
+ return toRootRelativePath(this.config.rootDir, filePath);
40
+ }
43
41
  getIslandBundleName(componentFile) {
44
- return `ecopages-react-island-${BigInt(`0x${contentHash(componentFile, 16)}`).toString()}`;
42
+ return `ecopages-react-island-${BigInt(`0x${contentHash(this.toSourceKey(componentFile), 16)}`).toString()}`;
43
+ }
44
+ getIslandComponentKey(island) {
45
+ return getIslandComponentKey(this.toSourceKey(island.file), island.config);
45
46
  }
46
47
  getIslandHydrationName(bundleName, componentKey) {
47
48
  return `${bundleName}-hydration-${componentKey}`;
48
49
  }
49
- getRouterPageGroupedEntryName(pagePath) {
50
+ getPageGroupedEntryName(pagePath) {
50
51
  const relativePath = path.relative(this.config.srcDir, pagePath);
51
52
  return relativePath
52
53
  .replace(/\.(tsx?|jsx?|mdx?)$/, '')
53
- .replace(/[\\/]+/g, '__')
54
+ .replace(/\/+/g, '__')
54
55
  .replace(/\[([^\]]+)\]/g, '_$1_');
55
56
  }
56
57
  /**
@@ -68,58 +69,39 @@ export class HydrationAssetService {
68
69
  }
69
70
  return `/${path
70
71
  .join(RESOLVED_ASSETS_DIR, path.relative(this.config.srcDir, pagePath))
71
- .replace(path.basename(pagePath), `${assetName}.js`)
72
- .replace(/\\/g, '/')}`;
72
+ .replace(path.basename(pagePath), `${assetName}.js`)}`;
73
73
  }
74
74
  /**
75
75
  * Creates the page-owned route entry asset for hydration and client navigation.
76
76
  *
77
77
  * @remarks
78
- * The entry is compiled asynchronously from the editable browser lifecycle.
79
- * Production router pages may be grouped into the Page Browser Graph, while
80
- * HMR entries remain separate ESM scripts with browser-resolvable imports.
78
+ * The entry imports the `@ecopages/react/page-hydration` lifecycle and React by package name. Outside HMR it is
79
+ * an entry of the app-wide browser build, so React and every other shared module are chunks it shares with the
80
+ * islands and the other Pages. With HMR it stays a separate unbundled ESM script whose imports core rewrites to
81
+ * dev-transform and vendor URLs.
81
82
  */
82
83
  async createPageDependencies(options) {
83
- const { pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, hmrEnabled, useBrowserRuntimeImports, isMdx, } = options;
84
- const runtimeImports = this.config.bundleService.getRuntimeImports();
85
- const groupedBundle = !hmrEnabled && this.config.routerAdapter
86
- ? {
87
- id: HydrationAssetService.ROUTER_PAGE_GROUPED_BUNDLE_ID,
88
- entryName: this.getRouterPageGroupedEntryName(pagePath),
89
- }
90
- : undefined;
91
- const bootstrapImports = resolveHydrationBootstrapImports({
92
- useBrowserRuntimeImports,
93
- runtimeImports,
94
- routerAdapterImportPath: this.config.routerAdapter?.bundle.importPath,
95
- });
96
- const pageHydrationScript = await this.pageScriptCompiler.compile({
84
+ const { pagePath, componentName, importPath, pageModuleUrlExpression, bundleOptions, hmrEnabled, isMdx } = options;
85
+ const groupedBundle = hmrEnabled
86
+ ? undefined
87
+ : { id: APP_BROWSER_CLIENT_BUNDLE_ID, entryName: this.getPageGroupedEntryName(pagePath) };
88
+ const pageHydrationScript = createPageEntrySource({
97
89
  importPath: hmrEnabled ? importPath : pagePath,
98
90
  pageModuleUrlExpression,
99
91
  scriptId: componentName,
100
- reactImportPath: bootstrapImports.reactImportPath,
101
- reactDomClientImportPath: bootstrapImports.reactDomClientImportPath,
102
- routerImportPath: bootstrapImports.routerImportPath,
103
- layoutComposeImportPath: bootstrapImports.layoutComposeImportPath,
104
- pageLayoutNormalizationImportPath: bootstrapImports.pageLayoutNormalizationImportPath,
92
+ routerImportPath: this.config.routerAdapter?.importPath,
105
93
  routerComponents: this.config.routerAdapter?.components,
106
94
  routerPropsExpression: this.config.routerAdapter?.getRouterProps('Page', 'props'),
107
95
  hmrEnabled,
108
96
  isMdx,
109
- minify: !hmrEnabled && isReactProductionRuntime(),
110
97
  });
111
98
  return [
112
99
  AssetFactory.createContentScript({
113
100
  position: 'head',
114
101
  content: pageHydrationScript,
115
102
  name: componentName,
103
+ bundledSourceFilepaths: [pagePath],
116
104
  packageRole: 'page-script',
117
- /**
118
- * @remarks
119
- * HMR bootstraps stay unbundled write-through ESM. Helper imports must
120
- * already be browser-resolvable vendor URLs from
121
- * {@link resolveHydrationBootstrapImports}.
122
- */
123
105
  bundle: !hmrEnabled,
124
106
  groupedBundle,
125
107
  bundleOptions,
@@ -152,7 +134,7 @@ export class HydrationAssetService {
152
134
  }
153
135
  return this.buildGroupedPageClientAssets(uniqueIslands, input.lazyEntries);
154
136
  }
155
- /** Collects React island hydration entries for the production app browser build. */
137
+ /** Collects React island hydration entries for a grouped browser build, which is the app-wide build in production. */
156
138
  async collectAppBrowserClientBuildEntries(islands) {
157
139
  const uniqueIslands = this.uniqueIslands(islands);
158
140
  const groupedEntrypointFiles = [...new Set(uniqueIslands.map(({ file }) => file))];
@@ -163,10 +145,9 @@ export class HydrationAssetService {
163
145
  for (const island of uniqueIslands) {
164
146
  const componentName = this.getIslandBundleName(island.file);
165
147
  const declaredModules = collectDeclaredModulesInConfig(island.config);
166
- const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, false, declaredModules, {}, island.file, groupedEntrypointFiles, groupedDeclaredModules);
167
- const componentKey = getIslandComponentKey(island.file, island.config);
168
- const hydrationName = this.getIslandHydrationName(componentName, componentKey);
169
- const hydrationScript = await this.createIslandHydrationScript(island.file, island.config, island.file, false);
148
+ const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, declaredModules, island.file, groupedEntrypointFiles, groupedDeclaredModules);
149
+ const hydrationName = this.getIslandHydrationName(componentName, this.getIslandComponentKey(island));
150
+ const hydrationScript = this.createIslandHydrationScript(island, island.file, false);
170
151
  entries.push({
171
152
  dependency: {
172
153
  ...hydrationScript,
@@ -181,12 +162,19 @@ export class HydrationAssetService {
181
162
  }
182
163
  return entries;
183
164
  }
184
- /** Keeps one entry per component; a file that declares several island components keeps each of them. */
165
+ /**
166
+ * Keeps one entry per component; a file that declares several island components keeps each of them.
167
+ *
168
+ * @remarks
169
+ * An island's `file` is its identity file, relative to the app root; it is resolved here so every later step
170
+ * bundles and watches the real file.
171
+ */
185
172
  uniqueIslands(islands) {
186
173
  const uniqueIslands = [];
187
174
  const seenKeys = new Set();
188
- for (const island of islands) {
189
- const key = getIslandComponentKey(island.file, island.config);
175
+ for (const input of islands) {
176
+ const island = { ...input, file: path.resolve(this.config.rootDir, input.file) };
177
+ const key = this.getIslandComponentKey(island);
190
178
  if (seenKeys.has(key)) {
191
179
  continue;
192
180
  }
@@ -199,100 +187,55 @@ export class HydrationAssetService {
199
187
  const processedAssets = [];
200
188
  for (const island of uniqueIslands) {
201
189
  this.config.hmrPageMetadataCache?.markOwnedEntrypoint(island.file);
202
- processedAssets.push(...(await this.buildHmrIslandAssets(island.file, island.config)));
190
+ processedAssets.push(...(await this.buildHmrIslandAssets(island)));
203
191
  }
204
192
  if (lazyEntries?.length) {
205
193
  processedAssets.push(...(await this.config.assetProcessingService.processDependencies(lazyEntries, this.config.assetProcessingIntegration)));
206
194
  }
207
195
  return processedAssets;
208
196
  }
197
+ /**
198
+ * Builds the island hydration entries and lazy entries in one grouped browser build.
199
+ *
200
+ * @remarks
201
+ * Each hydration entry imports its island module and React by package name, so the build shares React, the
202
+ * bootstrap and every common module between them as chunks.
203
+ */
209
204
  async buildGroupedPageClientAssets(uniqueIslands, lazyEntries) {
210
- const islandEntries = await this.createGroupedIslandEntries(uniqueIslands);
211
- const clientEntries = [...islandEntries, ...(lazyEntries ?? [])];
212
- const processedClientEntries = clientEntries.length > 0
213
- ? await this.config.assetProcessingService.processDependencies(clientEntries, this.config.assetProcessingIntegration)
214
- : [];
215
- const srcUrlByEntryName = this.indexSrcUrlsByEntryName(processedClientEntries);
216
- const hydrationScripts = await this.createGroupedHydrationScripts(uniqueIslands, srcUrlByEntryName);
217
- const processedHydration = hydrationScripts.length > 0
218
- ? await this.config.assetProcessingService.processDependencies(hydrationScripts, this.config.assetProcessingIntegration)
219
- : [];
220
- return [...processedClientEntries, ...processedHydration];
221
- }
222
- async createGroupedIslandEntries(uniqueIslands) {
223
- const islandEntries = [];
224
- const declaredModulesByFile = new Map();
225
- for (const { file, config } of uniqueIslands) {
226
- const declaredModules = declaredModulesByFile.get(file) ?? new Set();
227
- for (const module of collectDeclaredModulesInConfig(config))
228
- declaredModules.add(module);
229
- declaredModulesByFile.set(file, declaredModules);
230
- }
231
- const groupedEntrypointFiles = [...declaredModulesByFile.keys()];
232
- const groupedDeclaredModules = [
233
- ...new Set(uniqueIslands.flatMap(({ config }) => collectDeclaredModulesInConfig(config))),
234
- ];
235
- for (const [file, declaredModules] of declaredModulesByFile) {
236
- const componentName = this.getIslandBundleName(file);
237
- const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, false, [...declaredModules], {}, file, groupedEntrypointFiles, groupedDeclaredModules);
238
- islandEntries.push(createAppBrowserClientEntry({
239
- entryName: componentName,
240
- importPath: file,
241
- reexport: true,
242
- packageRole: 'dynamic-chunk',
243
- bundleOptions,
244
- attributes: {
245
- 'data-eco-persist': 'true',
246
- },
247
- }));
248
- }
249
- return islandEntries;
250
- }
251
- indexSrcUrlsByEntryName(processedClientEntries) {
252
- const srcUrlByEntryName = new Map();
253
- for (const processed of processedClientEntries) {
254
- const entryName = processed.groupedBundle?.entryName;
255
- if (entryName && processed.srcUrl) {
256
- srcUrlByEntryName.set(entryName, processed.srcUrl);
257
- }
258
- }
259
- return srcUrlByEntryName;
260
- }
261
- async createGroupedHydrationScripts(uniqueIslands, srcUrlByEntryName) {
262
- const hydrationScripts = [];
263
- for (const island of uniqueIslands) {
264
- const importPath = srcUrlByEntryName.get(this.getIslandBundleName(island.file));
265
- if (!importPath) {
266
- throw new Error(`Missing grouped browser output for island ${island.file}`);
267
- }
268
- hydrationScripts.push(await this.createIslandHydrationScript(island.file, island.config, importPath, false));
205
+ const hydrationEntries = await this.collectAppBrowserClientBuildEntries(uniqueIslands);
206
+ const clientEntries = [...hydrationEntries.map(({ dependency }) => dependency), ...(lazyEntries ?? [])];
207
+ if (clientEntries.length === 0) {
208
+ return [];
269
209
  }
270
- return hydrationScripts;
210
+ return this.config.assetProcessingService.processDependencies(clientEntries, this.config.assetProcessingIntegration);
271
211
  }
272
- async buildHmrIslandAssets(componentFile, config) {
273
- const importPath = await this.resolveAssetImportPath(componentFile, this.getIslandBundleName(componentFile));
274
- const hydrationScript = await this.createIslandHydrationScript(componentFile, config, importPath, true);
212
+ async buildHmrIslandAssets(island) {
213
+ const importPath = await this.resolveAssetImportPath(island.file, this.getIslandBundleName(island.file));
214
+ const hydrationScript = this.createIslandHydrationScript(island, importPath, true);
275
215
  return this.config.assetProcessingService.processDependencies([hydrationScript], this.config.assetProcessingIntegration);
276
216
  }
277
- async createIslandHydrationScript(componentFile, config, importPath, hmrEnabled) {
217
+ /**
218
+ * @remarks
219
+ * The entry lists the island file it imports by absolute path in `bundledSourceFilepaths`, so its dependency key
220
+ * hashes its text with that file written relative to the app root; its name hashes the root-relative path too.
221
+ */
222
+ createIslandHydrationScript(island, importPath, hmrEnabled) {
223
+ const { file: componentFile, config } = island;
278
224
  const componentName = this.getIslandBundleName(componentFile);
279
- const componentKey = getIslandComponentKey(componentFile, config);
225
+ const componentKey = this.getIslandComponentKey(island);
280
226
  const hydrationName = this.getIslandHydrationName(componentName, componentKey);
281
- const runtimeImports = this.config.bundleService.getRuntimeImports();
282
- const islandHydrationScript = await this.islandScriptCompiler.compile({
227
+ const islandHydrationScript = createIslandEntrySource({
283
228
  importPath,
284
229
  scriptId: hydrationName,
285
- reactImportPath: runtimeImports.react,
286
- reactDomClientImportPath: runtimeImports.reactDomClient,
287
230
  targetSelector: `[data-eco-component-key="${componentKey}"]`,
288
231
  componentRef: config?.identity?.id,
289
- minify: !hmrEnabled,
290
232
  hmrEnabled,
291
233
  });
292
234
  return AssetFactory.createContentScript({
293
235
  position: 'head',
294
236
  content: islandHydrationScript,
295
237
  name: hydrationName,
238
+ bundledSourceFilepaths: [componentFile],
296
239
  packageRole: 'keep-separate',
297
240
  bundle: false,
298
241
  attributes: {
@@ -307,29 +250,23 @@ export class HydrationAssetService {
307
250
  /**
308
251
  * Creates the page browser graph dependency declarations for a React page.
309
252
  *
310
- * @remarks
311
- * Chooses shared vendor import URLs when HMR is on, when running a non-production
312
- * hosted runtime with HMR off, or when a router adapter is configured (router
313
- * pages always externalize to shared runtimes). Production non-router pages
314
- * may inline React into the page bundle instead.
315
- *
316
253
  * @param pagePath - Absolute file path of the page
317
254
  * @param isMdx - Whether the page is an MDX file
318
255
  * @param declaredModules - Explicitly declared browser module specifiers
319
256
  */
320
257
  async createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules) {
321
- const componentName = `ecopages-react-${BigInt(`0x${contentHash(pagePath, 16)}`).toString()}`;
258
+ const componentName = `ecopages-react-${BigInt(`0x${contentHash(this.toSourceKey(pagePath), 16)}`).toString()}`;
322
259
  const hmrManager = this.config.assetProcessingService?.getHmrManager();
323
260
  const hmrEnabled = hmrManager?.isEnabled() ?? false;
324
- const productionRuntime = isReactProductionRuntime();
325
- const usesRouterRuntime = Boolean(this.config.routerAdapter);
326
- const useBrowserRuntimeImports = hmrEnabled || !productionRuntime || usesRouterRuntime;
327
261
  if (hmrEnabled) {
328
262
  this.config.hmrPageMetadataCache?.setDeclaredModules(pagePath, declaredModules);
329
263
  }
330
264
  const importPath = await this.resolveAssetImportPath(pagePath, componentName);
331
265
  const pageModuleUrlExpression = hmrEnabled ? JSON.stringify(importPath) : 'import.meta.url';
332
- const bundleOptions = await this.config.bundleService.createBundleOptions(componentName, isMdx, declaredModules, { includeRuntime: !useBrowserRuntimeImports, splitting: usesRouterRuntime }, pagePath);
266
+ const bundleOptions = {
267
+ ...(await this.config.bundleService.createBundleOptions(componentName, declaredModules, pagePath)),
268
+ splitting: true,
269
+ };
333
270
  const dependencies = await this.createPageDependencies({
334
271
  pagePath,
335
272
  componentName,
@@ -337,7 +274,6 @@ export class HydrationAssetService {
337
274
  pageModuleUrlExpression,
338
275
  bundleOptions,
339
276
  hmrEnabled,
340
- useBrowserRuntimeImports,
341
277
  isMdx,
342
278
  });
343
279
  return dependencies;
@@ -0,0 +1,17 @@
1
+ /** Complete inputs that affect an Island Host entry's generated source. */
2
+ export type IslandEntrySourceOptions = {
3
+ importPath: string;
4
+ scriptId: string;
5
+ targetSelector: string;
6
+ componentRef?: string;
7
+ hmrEnabled?: boolean;
8
+ };
9
+ /**
10
+ * Creates the Island Host entry that imports the component module and
11
+ * delegates lifecycle behavior to `@ecopages/react/island-hydration`.
12
+ *
13
+ * @remarks
14
+ * The entry imports React and the bootstrap by package name. Production bundles it into the app-wide build, and
15
+ * development rewrites those imports to their vendor URLs. No server process compiles the bootstrap.
16
+ */
17
+ export declare function createIslandEntrySource(options: IslandEntrySourceOptions): string;
@@ -0,0 +1,32 @@
1
+ import { ISLAND_HYDRATION_PACKAGE, REACT_DOM_CLIENT_PACKAGE, REACT_PACKAGE, } from '../bundling/bootstrap-package-paths.js';
2
+ /**
3
+ * Creates the Island Host entry that imports the component module and
4
+ * delegates lifecycle behavior to `@ecopages/react/island-hydration`.
5
+ *
6
+ * @remarks
7
+ * The entry imports React and the bootstrap by package name. Production bundles it into the app-wide build, and
8
+ * development rewrites those imports to their vendor URLs. No server process compiles the bootstrap.
9
+ */
10
+ export function createIslandEntrySource(options) {
11
+ const hmrSource = options.hmrEnabled
12
+ ? `registerIslandHmr(configuration, (url) => import(url), ${JSON.stringify(options.importPath)});`
13
+ : '';
14
+ return `
15
+ import { hydrateRoot } from ${JSON.stringify(REACT_DOM_CLIENT_PACKAGE)};
16
+ import { createElement, useEffect } from ${JSON.stringify(REACT_PACKAGE)};
17
+ import * as ComponentModule from ${JSON.stringify(options.importPath)};
18
+ import { getIslandHydrationRuntime, mountIslands, registerIslandHmr } from ${JSON.stringify(ISLAND_HYDRATION_PACKAGE)};
19
+
20
+ const configuration = {
21
+ targetSelector: ${JSON.stringify(options.targetSelector)},
22
+ componentModule: ComponentModule,
23
+ componentRef: ${JSON.stringify(options.componentRef ?? '')},
24
+ scriptId: ${JSON.stringify(options.scriptId)},
25
+ runtime: { hydrateRoot, createElement, useEffect },
26
+ runtimeState: getIslandHydrationRuntime()
27
+ };
28
+ const mount = () => mountIslands(configuration);
29
+ ${hmrSource}
30
+ document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", mount, { once: true }) : mount();
31
+ `.trim();
32
+ }
@@ -1,5 +1,23 @@
1
- import type { CompiledPageHydrationOptions } from './compiled-page-hydration-options.js';
1
+ /** Complete inputs that affect a Page hydration entry's generated source. */
2
+ export type PageEntrySourceOptions = {
3
+ importPath: string;
4
+ pageModuleUrlExpression: string;
5
+ scriptId: string;
6
+ routerImportPath?: string;
7
+ routerComponents?: {
8
+ router: string;
9
+ pageContent: string;
10
+ };
11
+ routerPropsExpression?: string;
12
+ hmrEnabled: boolean;
13
+ isMdx: boolean;
14
+ };
2
15
  /**
3
16
  * Creates the Page entry contract consumed by the browser lifecycle.
17
+ *
18
+ * @remarks
19
+ * The entry only wires the Page module to `@ecopages/react/page-hydration`. It imports React, the bootstrap and the
20
+ * router by package name, like any other module: production bundles them into the app-wide build, and development
21
+ * rewrites them to their vendor URLs.
4
22
  */
5
- export declare function createPageEntrySource(options: CompiledPageHydrationOptions): string;
23
+ export declare function createPageEntrySource(options: PageEntrySourceOptions): string;
@@ -1,3 +1,4 @@
1
+ import { LAYOUT_COMPOSE_PACKAGE, PAGE_HYDRATION_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE, REACT_DOM_CLIENT_PACKAGE, REACT_PACKAGE, } from '../bundling/bootstrap-package-paths.js';
1
2
  function assertRouterConfiguration(options) {
2
3
  if (options.routerComponents && !options.routerImportPath) {
3
4
  throw new Error('routerImportPath is required when router components are configured');
@@ -35,14 +36,12 @@ function buildRouterTree(options) {
35
36
  function buildNormalizationImport(options) {
36
37
  if (!options.isMdx)
37
38
  return '';
38
- return `import { ensurePageConfigLayouts } from ${JSON.stringify(options.pageLayoutNormalizationImportPath)};`;
39
+ return `import { ensurePageConfigLayouts } from ${JSON.stringify(PAGE_LAYOUT_NORMALIZATION_PACKAGE)};`;
39
40
  }
40
41
  function buildHmrOptions(options) {
41
42
  if (!options.hmrEnabled)
42
43
  return '';
43
- const layoutStack = options.routerComponents
44
- ? 'getLayoutStack: (Page) => (Page.config?.layouts ?? []).map((layout) => layout?.config?.identity?.id ?? "").join("|"),'
45
- : '';
44
+ const layoutStack = options.routerComponents ? 'getLayouts: (Page) => Page.config?.layouts ?? [],' : '';
46
45
  return `hmr: {
47
46
  importPath: ${JSON.stringify(options.importPath)},
48
47
  ${layoutStack}
@@ -50,17 +49,23 @@ function buildHmrOptions(options) {
50
49
  }
51
50
  /**
52
51
  * Creates the Page entry contract consumed by the browser lifecycle.
52
+ *
53
+ * @remarks
54
+ * The entry only wires the Page module to `@ecopages/react/page-hydration`. It imports React, the bootstrap and the
55
+ * router by package name, like any other module: production bundles them into the app-wide build, and development
56
+ * rewrites them to their vendor URLs.
53
57
  */
54
58
  export function createPageEntrySource(options) {
55
59
  assertRouterConfiguration(options);
56
- const pageBootstrapId = '\0ecopages-react-page-bootstrap';
57
- const pageDataReaderId = '\0ecopages-react-page-data-reader';
58
60
  return `
59
- import { hydrateRoot } from ${JSON.stringify(options.reactDomClientImportPath)};
60
- import { createElement } from ${JSON.stringify(options.reactImportPath)};
61
- import { resolvePageComponent, startPageHydration } from ${JSON.stringify(pageBootstrapId)};
62
- import { readPageDataDocument, getPageDataFromDocument } from ${JSON.stringify(pageDataReaderId)};
63
- ${options.routerComponents ? '' : `import { composeLayoutPageTree } from ${JSON.stringify(options.layoutComposeImportPath)};`}
61
+ import { hydrateRoot } from ${JSON.stringify(REACT_DOM_CLIENT_PACKAGE)};
62
+ import { createElement } from ${JSON.stringify(REACT_PACKAGE)};
63
+ import {
64
+ readPageDataDocument,
65
+ resolvePageComponent,
66
+ startPageHydration,
67
+ } from ${JSON.stringify(PAGE_HYDRATION_PACKAGE)};
68
+ ${options.routerComponents ? '' : `import { composeLayoutPageTree } from ${JSON.stringify(LAYOUT_COMPOSE_PACKAGE)};`}
64
69
  ${buildRouterImports(options)}
65
70
  ${buildNormalizationImport(options)}
66
71
  ${buildPageImport(options)}
@@ -73,7 +78,7 @@ startPageHydration({
73
78
  scriptId: ${JSON.stringify(options.scriptId)},
74
79
  pageModuleUrl,
75
80
  Page: initialPage,
76
- pageDataReader: { readPageDataDocument, getPageDataFromDocument },
81
+ pageDataReader: { readPageDataDocument },
77
82
  runtime: { hydrateRoot, createElement },
78
83
  createTree,
79
84
  hasRouter: ${Boolean(options.routerComponents)},
@@ -4,14 +4,11 @@ export type ReadPageDataDocumentResult = {
4
4
  props: EcoPageDataProps;
5
5
  };
6
6
  /**
7
- * Reads `__ECO_PAGE_DATA__`, supporting both v1 envelopes and legacy flat props.
7
+ * Reads `__ECO_PAGE_DATA__` from `source`, supporting both v1 envelopes and legacy flat props.
8
8
  *
9
9
  * @remarks
10
10
  * Always returns unwrapped `props`. `moduleUrl` is set only when the document
11
- * carries a valid v1 envelope.
11
+ * carries a valid v1 envelope. `source` defaults to the live document; a direct HMR update passes the document it
12
+ * fetched, whose data is the newer.
12
13
  */
13
- export declare function readPageDataDocument(): ReadPageDataDocumentResult;
14
- /**
15
- * Returns page props from `__ECO_PAGE_DATA__` for hydration and HMR handlers.
16
- */
17
- export declare function getPageDataFromDocument(): EcoPageDataProps;
14
+ export declare function readPageDataDocument(source?: Pick<Document, 'getElementById'>): ReadPageDataDocumentResult;
@@ -1,13 +1,14 @@
1
1
  import { resolveEcoPageDataModuleUrl, resolveEcoPageDataProps } from './page-data-manifest.js';
2
2
  /**
3
- * Reads `__ECO_PAGE_DATA__`, supporting both v1 envelopes and legacy flat props.
3
+ * Reads `__ECO_PAGE_DATA__` from `source`, supporting both v1 envelopes and legacy flat props.
4
4
  *
5
5
  * @remarks
6
6
  * Always returns unwrapped `props`. `moduleUrl` is set only when the document
7
- * carries a valid v1 envelope.
7
+ * carries a valid v1 envelope. `source` defaults to the live document; a direct HMR update passes the document it
8
+ * fetched, whose data is the newer.
8
9
  */
9
- export function readPageDataDocument() {
10
- const element = document.getElementById('__ECO_PAGE_DATA__');
10
+ export function readPageDataDocument(source = document) {
11
+ const element = source.getElementById('__ECO_PAGE_DATA__');
11
12
  if (!element?.textContent) {
12
13
  return { props: {} };
13
14
  }
@@ -23,9 +24,3 @@ export function readPageDataDocument() {
23
24
  return { props: {} };
24
25
  }
25
26
  }
26
- /**
27
- * Returns page props from `__ECO_PAGE_DATA__` for hydration and HMR handlers.
28
- */
29
- export function getPageDataFromDocument() {
30
- return readPageDataDocument().props;
31
- }
@@ -1,37 +1,32 @@
1
1
  import { type EcoComponent, type EcoComponentConfig } from '@ecopages/core';
2
- import { type AssetProcessingIntegration, type AssetProcessingService, type ProcessedAsset } from '@ecopages/core/integration';
2
+ import { type AssetDefinition } from '@ecopages/core/integration';
3
3
  import type { PageModuleService } from '../page/page-module.js';
4
- type MdxConfigDependencyProcessor = (components: Partial<EcoComponent>[]) => Promise<ProcessedAsset[]>;
5
4
  export interface MdxConfigDependencyServiceConfig {
6
5
  integrationName: string;
6
+ /** The app root that root-relative identity files resolve against. */
7
+ rootDir: string;
7
8
  pageModuleService: Pick<PageModuleService, 'ensureConfigFileMetadata'>;
8
- assetProcessingService: Pick<AssetProcessingService, 'processDependencies'>;
9
- assetProcessingIntegration?: AssetProcessingIntegration;
10
9
  }
11
10
  /**
12
11
  * Resolves MDX-owned config dependencies that live outside the normal React component tree.
13
12
  *
14
13
  * React MDX pages can declare dependencies on the page config itself or on a
15
- * resolved layout config. Those roots need to be materialized as synthetic
16
- * component configs so the shared dependency pipeline can process them without
17
- * growing more MDX-specific logic inside the renderer.
14
+ * resolved layout config. Those roots become synthetic component configs that core
15
+ * processes through the shared dependency pipeline, and plans for the app-wide browser build.
18
16
  */
19
17
  export declare class MdxConfigDependencyService {
20
18
  private readonly config;
21
19
  constructor(config: MdxConfigDependencyServiceConfig);
22
20
  /**
23
- * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
21
+ * Returns the MDX-owned config components and, as eager head scripts, their SSR-marked lazy scripts.
24
22
  */
25
- processMdxConfigDependencies(options: {
26
- pagePath: string;
27
- config?: EcoComponentConfig;
28
- processComponentDependencies: MdxConfigDependencyProcessor;
29
- }): Promise<ProcessedAsset[]>;
23
+ collectMdxConfigContribution(pagePath: string, config: EcoComponentConfig | undefined): {
24
+ components: Partial<EcoComponent>[];
25
+ bundledScripts: AssetDefinition[];
26
+ };
30
27
  private createOwnedConfigComponents;
31
- private processDeclaredSsrLazyDependencies;
32
28
  /**
33
29
  * Collects `lazy` script dependencies that also opt into SSR from an MDX config graph.
34
30
  */
35
31
  private collectDeclaredSsrLazyDependencies;
36
32
  }
37
- export {};