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

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 (57) hide show
  1. package/README.md +5 -1
  2. package/package.json +4 -4
  3. package/src/app/client-only.js +13 -17
  4. package/src/app/dynamic.js +7 -10
  5. package/src/app/dynamic.test.browser.js +27 -29
  6. package/src/bundling/bootstrap-package-paths.js +5 -6
  7. package/src/bundling/bundle.js +115 -114
  8. package/src/bundling/discover-layout-runtime-modules.js +166 -155
  9. package/src/bundling/runtime-alias-map.d.ts +4 -1
  10. package/src/bundling/runtime-alias-map.js +107 -95
  11. package/src/bundling/runtime-bundle.js +250 -274
  12. package/src/bundling/runtime-interop-plugin.js +31 -35
  13. package/src/bundling/runtime-mode.js +10 -5
  14. package/src/bundling/runtime-modules.js +46 -35
  15. package/src/client-graph/ast-transform.js +415 -305
  16. package/src/client-graph/boundary-cache.js +146 -104
  17. package/src/client-graph/boundary-plugin.js +122 -104
  18. package/src/client-graph/component-config-traversal.js +70 -49
  19. package/src/client-graph/declared-modules.js +63 -41
  20. package/src/client-graph/reachability-analyzer.js +506 -313
  21. package/src/client-graph/specifier-classification.js +209 -141
  22. package/src/contracts/router-adapter.js +6 -0
  23. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  24. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  25. package/src/hmr/hmr-scripts.js +22 -9
  26. package/src/hmr/hmr-strategy.d.ts +12 -181
  27. package/src/hmr/hmr-strategy.js +321 -650
  28. package/src/hmr/page-metadata-cache.js +43 -40
  29. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  30. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  31. package/src/hydration/assert-no-bare-ecopages-imports.js +6 -6
  32. package/src/hydration/bootstrap-imports.js +30 -20
  33. package/src/hydration/hydration-asset.js +216 -213
  34. package/src/hydration/hydration-scripts.d.ts +4 -0
  35. package/src/hydration/hydration-scripts.js +199 -66
  36. package/src/hydration/hydration-scripts.test.browser.js +163 -168
  37. package/src/hydration/page-data-manifest.js +89 -45
  38. package/src/hydration/page-data-reader.js +45 -32
  39. package/src/hydration/page-payload.js +101 -99
  40. package/src/hydration/serialize-page-data-script.js +27 -28
  41. package/src/mdx/mdx-config-dependency.js +108 -112
  42. package/src/mdx/mdx-loader-plugin.js +7 -10
  43. package/src/page/page-module.js +72 -66
  44. package/src/plugin/react.constants.js +1 -4
  45. package/src/plugin/react.plugin.d.ts +1 -0
  46. package/src/plugin/react.plugin.js +227 -216
  47. package/src/plugin/react.types.js +1 -0
  48. package/src/render/component-ownership.js +42 -18
  49. package/src/render/component-ssr.js +168 -190
  50. package/src/render/eco-embed.js +8 -10
  51. package/src/render/errors.js +21 -16
  52. package/src/render/html-boundary.js +55 -51
  53. package/src/render/layout-compose.js +122 -94
  54. package/src/render/react-renderer.js +433 -468
  55. package/src/render/react-runtime.js +25 -20
  56. package/src/render/unified-layout-composition.js +74 -85
  57. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
@@ -1,481 +1,446 @@
1
- import {
2
- IntegrationRenderer
3
- } from "@ecopages/core/route-renderer/orchestration/integration-renderer";
4
- import { RESOLVED_ASSETS_DIR } from "@ecopages/core/constants";
5
- import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from "@ecopages/core/router/navigation-coordinator";
6
- import { ensurePageConfigLayouts } from "@ecopages/core/eco/page-layout-normalization";
7
- import { REACT_PLUGIN_NAME } from "../plugin/react.constants.js";
8
- import { BundleService } from "../bundling/bundle.js";
9
- import { HmrPageMetadataCache } from "../hmr/page-metadata-cache.js";
10
- import { MdxConfigDependencyService } from "../mdx/mdx-config-dependency.js";
11
- import { PageModuleService } from "../page/page-module.js";
12
- import { PagePayloadService } from "../hydration/page-payload.js";
13
- import { HydrationAssetService } from "../hydration/hydration-asset.js";
14
- import {
15
- composeDocumentShell,
16
- finalizeDocumentShellHtml,
17
- renderPageDocumentShell
18
- } from "@ecopages/core/route-renderer/orchestration/document-shell/document-shell-render.service";
19
- import { mergePageBrowserGraph } from "@ecopages/core/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils";
20
- import {
21
- getForeignSubtreeResolutionContextKey,
22
- getForeignSubtreeTokenPrefix,
23
- resolveOwningIntegrationRenderer
24
- } from "@ecopages/core/route-renderer/orchestration/foreign-child/owning-renderer-resolution";
25
- import { asReactComponent, getComponentRequires, isReactManagedComponent } from "./component-ownership.js";
26
- import {
27
- createForeignSubtreeRuntimeContext,
28
- renderForeignComponentWithSerializedHtml,
29
- renderReactManagedComponent,
30
- renderReactQueuedForeignSubtreeChildren
31
- } from "./component-ssr.js";
32
- import { BundleError, ReactRenderError } from "./errors.js";
33
- import { resolveReactRuntimeModules } from "./react-runtime.js";
34
- import { composeReactLayoutPageChildren, resolveComposeChildren } from "./unified-layout-composition.js";
35
- import { BundleError as BundleError2, ReactRenderError as ReactRenderError2 } from "./errors.js";
36
- class ReactRenderer extends IntegrationRenderer {
37
- name = REACT_PLUGIN_NAME;
38
- componentDirectory = RESOLVED_ASSETS_DIR;
39
- reactRuntimeModules;
40
- routerAdapter;
41
- mdxCompilerOptions;
42
- mdxExtensions;
43
- hmrPageMetadataCache;
44
- /**
45
- * When true, always emit page browser graph / hydration assets for React pages.
46
- *
47
- * Mapped from the public `explicitGraph` plugin option. Does not disable the
48
- * client-graph AST boundary.
49
- */
50
- forceBrowserGraph;
51
- /** @internal */
52
- bundleService;
53
- /** @internal */
54
- pageModuleService;
55
- /** @internal */
56
- hydrationAssetService;
57
- /** @internal */
58
- pagePayloadService;
59
- /** @internal */
60
- mdxConfigDependencyService;
61
- constructor(options) {
62
- const { reactConfig, ...rendererOptions } = options;
63
- super(rendererOptions);
64
- this.routerAdapter = reactConfig?.routerAdapter;
65
- this.mdxCompilerOptions = reactConfig?.mdxCompilerOptions;
66
- this.mdxExtensions = reactConfig?.mdxExtensions ?? [".mdx"];
67
- this.hmrPageMetadataCache = reactConfig?.hmrPageMetadataCache;
68
- this.forceBrowserGraph = reactConfig?.forceBrowserGraph ?? false;
69
- this.bundleService = new BundleService({
70
- rootDir: this.appConfig.rootDir,
71
- appConfig: this.appConfig,
72
- hostIntegrationName: this.name,
73
- routerAdapter: this.routerAdapter,
74
- runtimeModules: reactConfig?.runtimeModules,
75
- mdxCompilerOptions: this.mdxCompilerOptions
76
- });
77
- this.pageModuleService = new PageModuleService({
78
- layoutsDir: this.appConfig.absolutePaths.layoutsDir,
79
- componentsDir: this.appConfig.absolutePaths.componentsDir,
80
- mdxExtensions: this.mdxExtensions,
81
- integrationName: this.name,
82
- hasRouterAdapter: Boolean(this.routerAdapter)
83
- });
84
- this.hydrationAssetService = new HydrationAssetService({
85
- srcDir: this.appConfig.srcDir,
86
- routerAdapter: this.routerAdapter,
87
- assetProcessingService: this.assetProcessingService,
88
- bundleService: this.bundleService,
89
- hmrPageMetadataCache: this.hmrPageMetadataCache
90
- });
91
- this.pagePayloadService = new PagePayloadService();
92
- this.mdxConfigDependencyService = new MdxConfigDependencyService({
93
- integrationName: this.name,
94
- pageModuleService: this.pageModuleService,
95
- assetProcessingService: this.assetProcessingService
96
- });
97
- }
98
- getRouterDocumentAttributes() {
99
- if (!this.routerAdapter) {
100
- return void 0;
1
+ /**
2
+ * React IntegrationRenderer orchestrator.
3
+ *
4
+ * @remarks
5
+ * Wires services and delegates SSR / layout composition / ownership details to
6
+ * focused modules under `render/`. Prefer changing those modules for
7
+ * implementation work; keep this file as the IntegrationRenderer seam.
8
+ *
9
+ * @module
10
+ */
11
+ import { IntegrationRenderer, } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
12
+ import { RESOLVED_ASSETS_DIR } from '@ecopages/core/constants';
13
+ import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from '@ecopages/core/router/navigation-coordinator';
14
+ import { ensurePageConfigLayouts } from '@ecopages/core/eco/page-layout-normalization';
15
+ import { REACT_PLUGIN_NAME } from '../plugin/react.constants.js';
16
+ import { BundleService } from '../bundling/bundle.js';
17
+ import { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
18
+ import { MdxConfigDependencyService } from '../mdx/mdx-config-dependency.js';
19
+ import { PageModuleService } from '../page/page-module.js';
20
+ import { PagePayloadService } from '../hydration/page-payload.js';
21
+ import { HydrationAssetService } from '../hydration/hydration-asset.js';
22
+ import { composeDocumentShell, finalizeDocumentShellHtml, renderPageDocumentShell, } from '@ecopages/core/route-renderer/orchestration/document-shell/document-shell-render.service';
23
+ import { mergePageBrowserGraph } from '@ecopages/core/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils';
24
+ import { getForeignSubtreeResolutionContextKey, getForeignSubtreeTokenPrefix, resolveOwningIntegrationRenderer, } from '@ecopages/core/route-renderer/orchestration/foreign-child/owning-renderer-resolution';
25
+ import { asReactComponent, getComponentRequires, isReactManagedComponent } from './component-ownership.js';
26
+ import { createForeignSubtreeRuntimeContext, renderForeignComponentWithSerializedHtml, renderReactManagedComponent, renderReactQueuedForeignSubtreeChildren, } from './component-ssr.js';
27
+ import { BundleError, ReactRenderError } from './errors.js';
28
+ import { resolveReactRuntimeModules } from './react-runtime.js';
29
+ import { composeReactLayoutPageChildren, resolveComposeChildren } from './unified-layout-composition.js';
30
+ export { BundleError, ReactRenderError } from './errors.js';
31
+ /**
32
+ * Renderer for React components.
33
+ * @extends IntegrationRenderer
34
+ */
35
+ export class ReactRenderer extends IntegrationRenderer {
36
+ name = REACT_PLUGIN_NAME;
37
+ componentDirectory = RESOLVED_ASSETS_DIR;
38
+ reactRuntimeModules;
39
+ routerAdapter;
40
+ mdxCompilerOptions;
41
+ mdxExtensions;
42
+ hmrPageMetadataCache;
43
+ /**
44
+ * When true, always emit page browser graph / hydration assets for React pages.
45
+ *
46
+ * Mapped from the public `explicitGraph` plugin option. Does not disable the
47
+ * client-graph AST boundary.
48
+ */
49
+ forceBrowserGraph;
50
+ /** @internal */
51
+ bundleService;
52
+ /** @internal */
53
+ pageModuleService;
54
+ /** @internal */
55
+ hydrationAssetService;
56
+ /** @internal */
57
+ pagePayloadService;
58
+ /** @internal */
59
+ mdxConfigDependencyService;
60
+ constructor(options) {
61
+ const { reactConfig, ...rendererOptions } = options;
62
+ super(rendererOptions);
63
+ this.routerAdapter = reactConfig?.routerAdapter;
64
+ this.mdxCompilerOptions = reactConfig?.mdxCompilerOptions;
65
+ this.mdxExtensions = reactConfig?.mdxExtensions ?? ['.mdx'];
66
+ this.hmrPageMetadataCache = reactConfig?.hmrPageMetadataCache;
67
+ this.forceBrowserGraph = reactConfig?.forceBrowserGraph ?? false;
68
+ this.bundleService = new BundleService({
69
+ rootDir: this.appConfig.rootDir,
70
+ appConfig: this.appConfig,
71
+ hostIntegrationName: this.name,
72
+ routerAdapter: this.routerAdapter,
73
+ runtimeModules: reactConfig?.runtimeModules,
74
+ mdxCompilerOptions: this.mdxCompilerOptions,
75
+ });
76
+ this.pageModuleService = new PageModuleService({
77
+ layoutsDir: this.appConfig.absolutePaths.layoutsDir,
78
+ componentsDir: this.appConfig.absolutePaths.componentsDir,
79
+ mdxExtensions: this.mdxExtensions,
80
+ integrationName: this.name,
81
+ hasRouterAdapter: Boolean(this.routerAdapter),
82
+ });
83
+ this.hydrationAssetService = new HydrationAssetService({
84
+ srcDir: this.appConfig.srcDir,
85
+ routerAdapter: this.routerAdapter,
86
+ assetProcessingService: this.assetProcessingService,
87
+ bundleService: this.bundleService,
88
+ hmrPageMetadataCache: this.hmrPageMetadataCache,
89
+ });
90
+ this.pagePayloadService = new PagePayloadService();
91
+ this.mdxConfigDependencyService = new MdxConfigDependencyService({
92
+ integrationName: this.name,
93
+ pageModuleService: this.pageModuleService,
94
+ assetProcessingService: this.assetProcessingService,
95
+ });
101
96
  }
102
- return {
103
- [ECO_DOCUMENT_OWNER_ATTRIBUTE]: "react-router"
104
- };
105
- }
106
- resolveReactRuntimeModules() {
107
- return resolveReactRuntimeModules(this.appConfig.rootDir);
108
- }
109
- getReactRuntimeModules() {
110
- this.reactRuntimeModules ??= this.resolveReactRuntimeModules();
111
- return this.reactRuntimeModules;
112
- }
113
- /**
114
- * Appends route hydration assets for a concrete page/view file to the current
115
- * HTML transformer state.
116
- */
117
- async appendHydrationAssetsForFile(filePath) {
118
- if (!filePath) {
119
- return;
97
+ getRouterDocumentAttributes() {
98
+ if (!this.routerAdapter) {
99
+ return undefined;
100
+ }
101
+ return {
102
+ [ECO_DOCUMENT_OWNER_ATTRIBUTE]: 'react-router',
103
+ };
104
+ }
105
+ resolveReactRuntimeModules() {
106
+ return resolveReactRuntimeModules(this.appConfig.rootDir);
107
+ }
108
+ getReactRuntimeModules() {
109
+ this.reactRuntimeModules ??= this.resolveReactRuntimeModules();
110
+ return this.reactRuntimeModules;
120
111
  }
121
- const pageBrowserGraph = await this.resolvePageBrowserGraphForFile(filePath);
122
- if (!pageBrowserGraph) {
123
- return;
112
+ /**
113
+ * Appends route hydration assets for a concrete page/view file to the current
114
+ * HTML transformer state.
115
+ */
116
+ async appendHydrationAssetsForFile(filePath) {
117
+ if (!filePath) {
118
+ return;
119
+ }
120
+ const pageBrowserGraph = await this.resolvePageBrowserGraphForFile(filePath);
121
+ if (!pageBrowserGraph) {
122
+ return;
123
+ }
124
+ const { pagePackage } = mergePageBrowserGraph(this.htmlTransformer.getPagePackage(), this.htmlTransformer.getProcessedDependencies(), pageBrowserGraph);
125
+ this.htmlTransformer.setPagePackage(pagePackage);
124
126
  }
125
- const { pagePackage } = mergePageBrowserGraph(
126
- this.htmlTransformer.getPagePackage(),
127
- this.htmlTransformer.getProcessedDependencies(),
128
- pageBrowserGraph
129
- );
130
- this.htmlTransformer.setPagePackage(pagePackage);
131
- }
132
- resolveOwningRenderer(integrationName, rendererCache) {
133
- return resolveOwningIntegrationRenderer({
134
- appConfig: this.appConfig,
135
- runtimeOrigin: this.runtimeOrigin,
136
- currentIntegrationName: this.name,
137
- currentRenderer: this,
138
- integrationName,
139
- cache: rendererCache
140
- });
141
- }
142
- resolveReactQueuedForeignSubtreeHtml(html, runtimeContext) {
143
- return this.foreignSubtreeExecutionService.resolveQueuedHtml({
144
- currentIntegrationName: this.name,
145
- html,
146
- runtimeContext,
147
- queueLabel: "React",
148
- getOwningRenderer: (integrationName, rendererCache) => this.resolveOwningRenderer(integrationName, rendererCache),
149
- applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
150
- dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
151
- renderQueuedChildren: (children, currentRuntimeContext, queuedResolutionsByToken, resolveToken) => renderReactQueuedForeignSubtreeChildren({
152
- children,
153
- currentRuntimeContext,
154
- queuedResolutionsByToken,
155
- resolveToken,
156
- runtime: this.getReactRuntimeModules(),
157
- integrationName: this.name,
158
- normalizeUnresolvedMarkerArtifactHtml: (value) => this.normalizeUnresolvedMarkerArtifactHtml(value),
159
- resolveQueuedTokens: (value, tokens, resolve) => this.foreignSubtreeExecutionService.resolveQueuedTokens(value, tokens, resolve)
160
- })
161
- });
162
- }
163
- /**
164
- * Renders a React component for component-level orchestration.
165
- *
166
- * Behavior:
167
- * - SSR always returns the component's own root HTML (no synthetic wrapper).
168
- * - When an explicit component instance id is provided, a stable
169
- * `data-eco-component-id` attribute is attached so island hydration can target it.
170
- * - Without an explicit instance id, component renders remain plain SSR output.
171
- * - When resolved child HTML is provided, that foreign subtree is treated as a pure SSR
172
- * composition step and does not emit hydration assets for the parent wrapper.
173
- *
174
- * This preserves DOM shape for global CSS/layout selectors while keeping a
175
- * deterministic mount target per component instance.
176
- */
177
- async renderComponent(input) {
178
- const runtimeContext = this.foreignSubtreeExecutionService.getQueuedRuntimeContext(
179
- input,
180
- getForeignSubtreeResolutionContextKey(this.name)
181
- );
182
- if (!isReactManagedComponent(input.component, this.name)) {
183
- return renderForeignComponentWithSerializedHtml({
184
- input,
185
- runtimeContext,
186
- integrationName: this.name,
187
- canResolveAssets: typeof this.assetProcessingService?.processDependencies === "function",
188
- processComponentDependencies: (components) => this.processComponentDependencies(components),
189
- dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
190
- getRootTagName: (html) => this.getRootTagName(html),
191
- resolveQueuedForeignSubtreeHtml: (html, context) => this.resolveReactQueuedForeignSubtreeHtml(html, context)
192
- });
127
+ resolveOwningRenderer(integrationName, rendererCache) {
128
+ return resolveOwningIntegrationRenderer({
129
+ appConfig: this.appConfig,
130
+ runtimeOrigin: this.runtimeOrigin,
131
+ currentIntegrationName: this.name,
132
+ currentRenderer: this,
133
+ integrationName,
134
+ cache: rendererCache,
135
+ });
193
136
  }
194
- return renderReactManagedComponent({
195
- input,
196
- runtimeContext,
197
- runtime: this.getReactRuntimeModules(),
198
- integrationName: this.name,
199
- normalizeUnresolvedMarkerArtifactHtml: (html) => this.normalizeUnresolvedMarkerArtifactHtml(html),
200
- resolveQueuedForeignSubtreeHtml: (html, context) => this.resolveReactQueuedForeignSubtreeHtml(html, context),
201
- getRootTagName: (html) => this.getRootTagName(html),
202
- dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
203
- hydrationAssetService: this.hydrationAssetService,
204
- canBuildIslandAssets: Boolean(this.assetProcessingService)
205
- });
206
- }
207
- createForeignChildRuntime(options) {
208
- return this.foreignSubtreeExecutionService.createQueuedRuntime({
209
- renderInput: options.renderInput,
210
- rendererCache: options.rendererCache,
211
- runtimeContextKey: getForeignSubtreeResolutionContextKey(this.name),
212
- tokenPrefix: getForeignSubtreeTokenPrefix(this.name),
213
- createRuntimeContext: (integrationContext, rendererCache) => createForeignSubtreeRuntimeContext({
214
- rendererCache,
215
- componentInstanceScope: integrationContext.componentInstanceId
216
- })
217
- });
218
- }
219
- /**
220
- * Checks if the given file path corresponds to an MDX file based on configured extensions.
221
- * @param filePath - The file path to check
222
- * @returns True if the file is an MDX file
223
- */
224
- isMdxFile(filePath) {
225
- return this.pageModuleService.isMdxFile(filePath);
226
- }
227
- normalizeImportedPageFile(file, pageModule) {
228
- const reactModule = pageModule;
229
- const { default: Page, getMetadata, config } = reactModule;
230
- if (this.pageModuleService.isMdxFile(file) && config) {
231
- ensurePageConfigLayouts(config);
232
- Page.config = config;
137
+ resolveReactQueuedForeignSubtreeHtml(html, runtimeContext) {
138
+ return this.foreignSubtreeExecutionService.resolveQueuedHtml({
139
+ currentIntegrationName: this.name,
140
+ html,
141
+ runtimeContext,
142
+ queueLabel: 'React',
143
+ getOwningRenderer: (integrationName, rendererCache) => this.resolveOwningRenderer(integrationName, rendererCache),
144
+ applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
145
+ dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
146
+ renderQueuedChildren: (children, currentRuntimeContext, queuedResolutionsByToken, resolveToken) => renderReactQueuedForeignSubtreeChildren({
147
+ children,
148
+ currentRuntimeContext,
149
+ queuedResolutionsByToken,
150
+ resolveToken,
151
+ runtime: this.getReactRuntimeModules(),
152
+ integrationName: this.name,
153
+ normalizeUnresolvedMarkerArtifactHtml: (value) => this.normalizeUnresolvedMarkerArtifactHtml(value),
154
+ resolveQueuedTokens: (value, tokens, resolve) => this.foreignSubtreeExecutionService.resolveQueuedTokens(value, tokens, resolve),
155
+ }),
156
+ });
233
157
  }
234
- return {
235
- ...pageModule,
236
- default: Page,
237
- getMetadata,
238
- config
239
- };
240
- }
241
- async collectPageBrowserGraphContribution(context) {
242
- try {
243
- const { file: pagePath, pageModule } = context;
244
- const shouldHydrate = this.forceBrowserGraph ? true : this.pageModuleService.shouldHydratePage(pageModule);
245
- if (!shouldHydrate) {
246
- return { assets: [] };
247
- }
248
- const isMdx = this.pageModuleService.isMdxFile(pagePath);
249
- const declaredModules = this.pageModuleService.collectPageDeclaredModules(pageModule);
250
- if (isMdx) {
251
- await this.bundleService.ensurePageLayoutNormalizationVendorProcessed(this.assetProcessingService);
252
- }
253
- const dependencies = await this.hydrationAssetService.createPageBrowserGraphDependencies(
254
- pagePath,
255
- isMdx,
256
- declaredModules
257
- );
258
- const assets = isMdx ? await this.mdxConfigDependencyService.processMdxConfigDependencies({
259
- pagePath,
260
- config: pageModule.config,
261
- processComponentDependencies: async (components) => await this.processComponentDependencies(components)
262
- }) : [];
263
- return { dependencies, assets };
264
- } catch (error) {
265
- if (error instanceof BundleError) {
266
- console.error("[ecopages] Bundle errors:", error.logs);
267
- }
268
- throw new ReactRenderError(
269
- `Failed to generate hydration script: ${error instanceof Error ? error.message : String(error)}`
270
- );
158
+ /**
159
+ * Renders a React component for component-level orchestration.
160
+ *
161
+ * Behavior:
162
+ * - SSR always returns the component's own root HTML (no synthetic wrapper).
163
+ * - When an explicit component instance id is provided, a stable
164
+ * `data-eco-component-id` attribute is attached so island hydration can target it.
165
+ * - Without an explicit instance id, component renders remain plain SSR output.
166
+ * - When resolved child HTML is provided, that foreign subtree is treated as a pure SSR
167
+ * composition step and does not emit hydration assets for the parent wrapper.
168
+ *
169
+ * This preserves DOM shape for global CSS/layout selectors while keeping a
170
+ * deterministic mount target per component instance.
171
+ */
172
+ async renderComponent(input) {
173
+ const runtimeContext = this.foreignSubtreeExecutionService.getQueuedRuntimeContext(input, getForeignSubtreeResolutionContextKey(this.name));
174
+ if (!isReactManagedComponent(input.component, this.name)) {
175
+ return renderForeignComponentWithSerializedHtml({
176
+ input,
177
+ runtimeContext,
178
+ integrationName: this.name,
179
+ canResolveAssets: typeof this.assetProcessingService?.processDependencies === 'function',
180
+ processComponentDependencies: (components) => this.processComponentDependencies(components),
181
+ dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
182
+ getRootTagName: (html) => this.getRootTagName(html),
183
+ resolveQueuedForeignSubtreeHtml: (html, context) => this.resolveReactQueuedForeignSubtreeHtml(html, context),
184
+ });
185
+ }
186
+ return renderReactManagedComponent({
187
+ input,
188
+ runtimeContext,
189
+ runtime: this.getReactRuntimeModules(),
190
+ integrationName: this.name,
191
+ normalizeUnresolvedMarkerArtifactHtml: (html) => this.normalizeUnresolvedMarkerArtifactHtml(html),
192
+ resolveQueuedForeignSubtreeHtml: (html, context) => this.resolveReactQueuedForeignSubtreeHtml(html, context),
193
+ getRootTagName: (html) => this.getRootTagName(html),
194
+ dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
195
+ hydrationAssetService: this.hydrationAssetService,
196
+ canBuildIslandAssets: Boolean(this.assetProcessingService),
197
+ });
271
198
  }
272
- }
273
- async composeReactLayoutPageChildrenForShell(page, context) {
274
- return composeReactLayoutPageChildren({
275
- page,
276
- context,
277
- runtime: this.getReactRuntimeModules(),
278
- integrationName: this.name,
279
- normalizeUnresolvedMarkerArtifactHtml: (html) => this.normalizeUnresolvedMarkerArtifactHtml(html),
280
- getRootTagName: (html) => this.getRootTagName(html),
281
- getQueuedForeignSubtreeResolutionContext: (input) => this.foreignSubtreeExecutionService.getQueuedRuntimeContext(
282
- input,
283
- getForeignSubtreeResolutionContextKey(this.name)
284
- ),
285
- resolveQueuedForeignSubtreeHtml: (html, runtimeContext) => this.resolveReactQueuedForeignSubtreeHtml(html, runtimeContext)
286
- });
287
- }
288
- async renderPageWithDocumentShell(input) {
289
- const shellLayouts = input.layouts ?? (input.layout ? [input.layout] : []);
290
- const composeChildren = resolveComposeChildren({
291
- page: input.page,
292
- shellLayouts,
293
- reactIntegrationName: this.name,
294
- composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context)
295
- });
296
- return renderPageDocumentShell(
297
- {
298
- renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
299
- appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups)
300
- },
301
- {
302
- ...input,
303
- composeChildren
304
- },
305
- this.DOC_TYPE
306
- );
307
- }
308
- /**
309
- * Renders a full route response for the filesystem page pipeline.
310
- *
311
- * This path receives already-resolved route metadata, layout, locals, and HTML
312
- * template instances from the shared renderer orchestration. Its main job is to
313
- * serialize only the browser-safe page payload, compose the mixed React/non-
314
- * React shell tree, and hand the result back as a document body.
315
- */
316
- async render({
317
- params,
318
- query,
319
- props,
320
- locals,
321
- pageLocals,
322
- metadata,
323
- Page,
324
- Layout,
325
- HtmlTemplate,
326
- pageProps,
327
- pagePackage
328
- }) {
329
- try {
330
- const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(pagePackage, {
331
- routerEnabled: Boolean(this.routerAdapter)
332
- });
333
- const safeLocals = this.pagePayloadService.getSerializableLocals(locals, getComponentRequires(Page));
334
- const allPageProps = this.pagePayloadService.buildSerializedPageProps({
335
- pageProps,
336
- params,
337
- query,
338
- safeLocals
339
- });
340
- return await this.renderPageWithDocumentShell({
341
- page: {
342
- component: Page,
343
- props: { params, query, ...props, locals: pageLocals }
344
- },
345
- layout: Layout ? {
346
- component: Layout,
347
- props: locals ? { locals } : {}
348
- } : void 0,
349
- htmlTemplate: HtmlTemplate,
350
- metadata,
351
- pageProps: allPageProps,
352
- documentProps: pageModuleUrl ? { pageModuleUrl } : void 0
353
- });
354
- } catch (error) {
355
- throw this.createRenderError("Failed to render component", error);
199
+ createForeignChildRuntime(options) {
200
+ return this.foreignSubtreeExecutionService.createQueuedRuntime({
201
+ renderInput: options.renderInput,
202
+ rendererCache: options.rendererCache,
203
+ runtimeContextKey: getForeignSubtreeResolutionContextKey(this.name),
204
+ tokenPrefix: getForeignSubtreeTokenPrefix(this.name),
205
+ createRuntimeContext: (integrationContext, rendererCache) => createForeignSubtreeRuntimeContext({
206
+ rendererCache: rendererCache,
207
+ componentInstanceScope: integrationContext.componentInstanceId,
208
+ }),
209
+ });
356
210
  }
357
- }
358
- getHtmlDocumentContributions(options) {
359
- if (options.partial || !options.renderOptions) {
360
- return void 0;
211
+ /**
212
+ * Checks if the given file path corresponds to an MDX file based on configured extensions.
213
+ * @param filePath - The file path to check
214
+ * @returns True if the file is an MDX file
215
+ */
216
+ isMdxFile(filePath) {
217
+ return this.pageModuleService.isMdxFile(filePath);
218
+ }
219
+ normalizeImportedPageFile(file, pageModule) {
220
+ const reactModule = pageModule;
221
+ const { default: Page, getMetadata, config } = reactModule;
222
+ if (this.pageModuleService.isMdxFile(file) && config) {
223
+ ensurePageConfigLayouts(config);
224
+ Page.config = config;
225
+ }
226
+ return {
227
+ ...pageModule,
228
+ default: Page,
229
+ getMetadata,
230
+ config,
231
+ };
232
+ }
233
+ async collectPageBrowserGraphContribution(context) {
234
+ try {
235
+ const { file: pagePath, pageModule } = context;
236
+ const shouldHydrate = this.forceBrowserGraph ? true : this.pageModuleService.shouldHydratePage(pageModule);
237
+ if (!shouldHydrate) {
238
+ return { assets: [] };
239
+ }
240
+ const isMdx = this.pageModuleService.isMdxFile(pagePath);
241
+ const declaredModules = this.pageModuleService.collectPageDeclaredModules(pageModule);
242
+ if (isMdx) {
243
+ await this.bundleService.ensurePageLayoutNormalizationVendorProcessed(this.assetProcessingService);
244
+ }
245
+ const dependencies = await this.hydrationAssetService.createPageBrowserGraphDependencies(pagePath, isMdx, declaredModules);
246
+ const assets = isMdx
247
+ ? await this.mdxConfigDependencyService.processMdxConfigDependencies({
248
+ pagePath,
249
+ config: pageModule.config,
250
+ processComponentDependencies: async (components) => await this.processComponentDependencies(components),
251
+ })
252
+ : [];
253
+ return { dependencies, assets };
254
+ }
255
+ catch (error) {
256
+ if (error instanceof BundleError) {
257
+ console.error('[ecopages] Bundle errors:', error.logs);
258
+ }
259
+ throw new ReactRenderError(`Failed to generate hydration script: ${error instanceof Error ? error.message : String(error)}`);
260
+ }
361
261
  }
362
- const safeLocals = this.pagePayloadService.getSerializableLocals(
363
- options.renderOptions.locals,
364
- getComponentRequires(options.renderOptions.Page)
365
- );
366
- const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(options.renderOptions.pagePackage, {
367
- routerEnabled: Boolean(this.routerAdapter)
368
- });
369
- const allPageProps = this.pagePayloadService.buildSerializedPageProps({
370
- pageProps: options.renderOptions.pageProps,
371
- params: options.renderOptions.params,
372
- query: options.renderOptions.query,
373
- safeLocals
374
- });
375
- return this.pagePayloadService.buildNonReactDocumentContributions({
376
- htmlTemplate: options.renderOptions.HtmlTemplate,
377
- pageProps: allPageProps,
378
- pageModuleUrl,
379
- reactIntegrationName: this.name,
380
- routerEnabled: Boolean(this.routerAdapter)
381
- });
382
- }
383
- getDocumentAttributes() {
384
- return this.getRouterDocumentAttributes();
385
- }
386
- async renderViewWithDocumentShell(input) {
387
- const normalizedProps = input.props ?? {};
388
- if (input.ctx.partial) {
389
- const { react, reactDomServer } = this.getReactRuntimeModules();
390
- const ViewComponent = asReactComponent(input.view);
391
- return this.renderPartialViewResponse({
392
- ...input,
393
- renderInline: async () => await reactDomServer.renderToReadableStream(react.createElement(ViewComponent, normalizedProps))
394
- });
262
+ async composeReactLayoutPageChildrenForShell(page, context) {
263
+ return composeReactLayoutPageChildren({
264
+ page,
265
+ context,
266
+ runtime: this.getReactRuntimeModules(),
267
+ integrationName: this.name,
268
+ normalizeUnresolvedMarkerArtifactHtml: (html) => this.normalizeUnresolvedMarkerArtifactHtml(html),
269
+ getRootTagName: (html) => this.getRootTagName(html),
270
+ getQueuedForeignSubtreeResolutionContext: (input) => this.foreignSubtreeExecutionService.getQueuedRuntimeContext(input, getForeignSubtreeResolutionContextKey(this.name)),
271
+ resolveQueuedForeignSubtreeHtml: (html, runtimeContext) => this.resolveReactQueuedForeignSubtreeHtml(html, runtimeContext),
272
+ });
395
273
  }
396
- await this.prepareViewDependencies(input.view, input.layout);
397
- if (!input.ctx.partial) {
398
- await this.appendHydrationAssetsForFile(input.view.config?.__eco?.file);
274
+ async renderPageWithDocumentShell(input) {
275
+ const shellLayouts = input.layouts ?? (input.layout ? [input.layout] : []);
276
+ const composeChildren = resolveComposeChildren({
277
+ page: input.page,
278
+ shellLayouts,
279
+ reactIntegrationName: this.name,
280
+ composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context),
281
+ });
282
+ return renderPageDocumentShell({
283
+ renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
284
+ appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
285
+ }, {
286
+ ...input,
287
+ composeChildren,
288
+ }, this.DOC_TYPE);
399
289
  }
400
- const HtmlTemplate = await this.getHtmlTemplate();
401
- const metadata = await this.resolveViewMetadata(input.view, input.props);
402
- const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(this.htmlTransformer.getPagePackage(), {
403
- routerEnabled: Boolean(this.routerAdapter)
404
- });
405
- const serializedPageProps = this.pagePayloadService.buildSerializedPageProps({
406
- pageProps: normalizedProps,
407
- params: {},
408
- query: {},
409
- safeLocals: this.pagePayloadService.getSerializableLocals(void 0, getComponentRequires(input.view))
410
- });
411
- const shellLayouts = input.layout ? [{ component: input.layout, props: {} }] : [];
412
- const composeChildren = resolveComposeChildren({
413
- page: { component: input.view, props: normalizedProps },
414
- shellLayouts,
415
- reactIntegrationName: this.name,
416
- composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context)
417
- });
418
- const { documentHtml } = await composeDocumentShell(
419
- {
420
- renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
421
- appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups)
422
- },
423
- {
424
- primaryComponent: input.view,
425
- primaryProps: normalizedProps,
426
- layout: input.layout ? {
427
- component: input.layout,
428
- props: {}
429
- } : void 0,
430
- layouts: shellLayouts.length > 0 ? shellLayouts : void 0,
431
- composeChildren,
432
- htmlTemplate: HtmlTemplate,
433
- documentProps: {
434
- metadata,
435
- pageProps: serializedPageProps,
436
- ...pageModuleUrl && { pageModuleUrl }
290
+ /**
291
+ * Renders a full route response for the filesystem page pipeline.
292
+ *
293
+ * This path receives already-resolved route metadata, layout, locals, and HTML
294
+ * template instances from the shared renderer orchestration. Its main job is to
295
+ * serialize only the browser-safe page payload, compose the mixed React/non-
296
+ * React shell tree, and hand the result back as a document body.
297
+ */
298
+ async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, pageProps, pagePackage, }) {
299
+ try {
300
+ const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(pagePackage, {
301
+ routerEnabled: Boolean(this.routerAdapter),
302
+ });
303
+ const safeLocals = this.pagePayloadService.getSerializableLocals(locals, getComponentRequires(Page));
304
+ const allPageProps = this.pagePayloadService.buildSerializedPageProps({
305
+ pageProps,
306
+ params,
307
+ query,
308
+ safeLocals,
309
+ });
310
+ return await this.renderPageWithDocumentShell({
311
+ page: {
312
+ component: Page,
313
+ props: { params, query, ...props, locals: pageLocals },
314
+ },
315
+ layout: Layout
316
+ ? {
317
+ component: Layout,
318
+ props: locals ? { locals } : {},
319
+ }
320
+ : undefined,
321
+ htmlTemplate: HtmlTemplate,
322
+ metadata,
323
+ pageProps: allPageProps,
324
+ documentProps: pageModuleUrl ? { pageModuleUrl } : undefined,
325
+ });
326
+ }
327
+ catch (error) {
328
+ throw this.createRenderError('Failed to render component', error);
329
+ }
330
+ }
331
+ getHtmlDocumentContributions(options) {
332
+ if (options.partial || !options.renderOptions) {
333
+ return undefined;
334
+ }
335
+ const safeLocals = this.pagePayloadService.getSerializableLocals(options.renderOptions.locals, getComponentRequires(options.renderOptions.Page));
336
+ const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(options.renderOptions.pagePackage, {
337
+ routerEnabled: Boolean(this.routerAdapter),
338
+ });
339
+ const allPageProps = this.pagePayloadService.buildSerializedPageProps({
340
+ pageProps: options.renderOptions.pageProps,
341
+ params: options.renderOptions.params,
342
+ query: options.renderOptions.query,
343
+ safeLocals,
344
+ });
345
+ return this.pagePayloadService.buildNonReactDocumentContributions({
346
+ htmlTemplate: options.renderOptions.HtmlTemplate,
347
+ pageProps: allPageProps,
348
+ pageModuleUrl,
349
+ reactIntegrationName: this.name,
350
+ routerEnabled: Boolean(this.routerAdapter),
351
+ });
352
+ }
353
+ getDocumentAttributes() {
354
+ return this.getRouterDocumentAttributes();
355
+ }
356
+ async renderViewWithDocumentShell(input) {
357
+ const normalizedProps = (input.props ?? {});
358
+ if (input.ctx.partial) {
359
+ const { react, reactDomServer } = this.getReactRuntimeModules();
360
+ const ViewComponent = asReactComponent(input.view);
361
+ return this.renderPartialViewResponse({
362
+ ...input,
363
+ renderInline: async () => await reactDomServer.renderToReadableStream(react.createElement(ViewComponent, normalizedProps)),
364
+ });
365
+ }
366
+ await this.prepareViewDependencies(input.view, input.layout);
367
+ if (!input.ctx.partial) {
368
+ await this.appendHydrationAssetsForFile(input.view.config?.__eco?.file);
369
+ }
370
+ const HtmlTemplate = await this.getHtmlTemplate();
371
+ const metadata = await this.resolveViewMetadata(input.view, input.props);
372
+ const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(this.htmlTransformer.getPagePackage(), {
373
+ routerEnabled: Boolean(this.routerAdapter),
374
+ });
375
+ const serializedPageProps = this.pagePayloadService.buildSerializedPageProps({
376
+ pageProps: normalizedProps,
377
+ params: {},
378
+ query: {},
379
+ safeLocals: this.pagePayloadService.getSerializableLocals(undefined, getComponentRequires(input.view)),
380
+ });
381
+ const shellLayouts = input.layout ? [{ component: input.layout, props: {} }] : [];
382
+ const composeChildren = resolveComposeChildren({
383
+ page: { component: input.view, props: normalizedProps },
384
+ shellLayouts,
385
+ reactIntegrationName: this.name,
386
+ composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context),
387
+ });
388
+ const { documentHtml } = await composeDocumentShell({
389
+ renderComponentWithForeignChildren: (renderInput) => this.renderComponentWithForeignChildren(renderInput),
390
+ appendProcessedDependencies: (...assetGroups) => this.appendProcessedDependencies(...assetGroups),
391
+ }, {
392
+ primaryComponent: input.view,
393
+ primaryProps: normalizedProps,
394
+ layout: input.layout
395
+ ? {
396
+ component: input.layout,
397
+ props: {},
398
+ }
399
+ : undefined,
400
+ layouts: shellLayouts.length > 0 ? shellLayouts : undefined,
401
+ composeChildren,
402
+ htmlTemplate: HtmlTemplate,
403
+ documentProps: {
404
+ metadata,
405
+ pageProps: serializedPageProps,
406
+ ...(pageModuleUrl && { pageModuleUrl }),
407
+ },
408
+ });
409
+ this.appendProcessedDependencies(this.getRendererBootstrapDependencies(false));
410
+ const html = await finalizeDocumentShellHtml(this.htmlTransformer, {
411
+ html: `${this.DOC_TYPE}${documentHtml}`,
412
+ partial: false,
413
+ documentAttributes: this.getRouterDocumentAttributes(),
414
+ htmlContributions: this.pagePayloadService.buildNonReactDocumentContributions({
415
+ htmlTemplate: HtmlTemplate,
416
+ pageProps: serializedPageProps,
417
+ pageModuleUrl,
418
+ reactIntegrationName: this.name,
419
+ routerEnabled: Boolean(this.routerAdapter),
420
+ }),
421
+ });
422
+ return this.createHtmlResponse(html, input.ctx);
423
+ }
424
+ /**
425
+ * Renders an arbitrary React view through the application's HTML shell.
426
+ *
427
+ * Unlike route rendering, this path starts from a single component rather than a
428
+ * page module discovered by the router. It still needs to resolve metadata,
429
+ * layout dependencies, and hydration assets so direct `ctx.render()` calls match
430
+ * normal page responses.
431
+ */
432
+ async renderToResponse(view, props, ctx) {
433
+ try {
434
+ const layouts = view.config?.layouts;
435
+ return await this.renderViewWithDocumentShell({
436
+ view,
437
+ props,
438
+ ctx,
439
+ layout: layouts?.[layouts.length - 1],
440
+ });
441
+ }
442
+ catch (error) {
443
+ throw this.createRenderError('Failed to render view', error);
437
444
  }
438
- }
439
- );
440
- this.appendProcessedDependencies(this.getRendererBootstrapDependencies(false));
441
- const html = await finalizeDocumentShellHtml(this.htmlTransformer, {
442
- html: `${this.DOC_TYPE}${documentHtml}`,
443
- partial: false,
444
- documentAttributes: this.getRouterDocumentAttributes(),
445
- htmlContributions: this.pagePayloadService.buildNonReactDocumentContributions({
446
- htmlTemplate: HtmlTemplate,
447
- pageProps: serializedPageProps,
448
- pageModuleUrl,
449
- reactIntegrationName: this.name,
450
- routerEnabled: Boolean(this.routerAdapter)
451
- })
452
- });
453
- return this.createHtmlResponse(html, input.ctx);
454
- }
455
- /**
456
- * Renders an arbitrary React view through the application's HTML shell.
457
- *
458
- * Unlike route rendering, this path starts from a single component rather than a
459
- * page module discovered by the router. It still needs to resolve metadata,
460
- * layout dependencies, and hydration assets so direct `ctx.render()` calls match
461
- * normal page responses.
462
- */
463
- async renderToResponse(view, props, ctx) {
464
- try {
465
- const layouts = view.config?.layouts;
466
- return await this.renderViewWithDocumentShell({
467
- view,
468
- props,
469
- ctx,
470
- layout: layouts?.[layouts.length - 1]
471
- });
472
- } catch (error) {
473
- throw this.createRenderError("Failed to render view", error);
474
445
  }
475
- }
476
446
  }
477
- export {
478
- BundleError2 as BundleError,
479
- ReactRenderError2 as ReactRenderError,
480
- ReactRenderer
481
- };