@ecopages/react 0.2.0-rc.1 → 0.2.0-rc.10

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 (83) hide show
  1. package/README.md +68 -14
  2. package/package.json +17 -5
  3. package/src/app/client-only.js +3 -8
  4. package/src/bundling/bundle.js +4 -1
  5. package/src/bundling/runtime-alias-map.d.ts +0 -1
  6. package/src/bundling/runtime-alias-map.js +1 -4
  7. package/src/bundling/runtime-bundle.d.ts +9 -2
  8. package/src/bundling/runtime-bundle.js +27 -16
  9. package/src/bundling/runtime-modules.d.ts +21 -0
  10. package/src/bundling/runtime-modules.js +25 -0
  11. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  12. package/src/client-graph/ast-transform-eco-page.js +71 -0
  13. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  14. package/src/client-graph/ast-transform-import-edits.js +75 -0
  15. package/src/client-graph/ast-transform-walk-imports.d.ts +19 -0
  16. package/src/client-graph/ast-transform-walk-imports.js +103 -0
  17. package/src/client-graph/ast-transform.d.ts +1 -7
  18. package/src/client-graph/ast-transform.js +42 -378
  19. package/src/client-graph/ast-walk.d.ts +10 -0
  20. package/src/client-graph/ast-walk.js +26 -0
  21. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +8 -0
  22. package/src/client-graph/boundary-plugin-read-file-inline.js +45 -0
  23. package/src/client-graph/boundary-plugin-transform.d.ts +18 -0
  24. package/src/client-graph/boundary-plugin-transform.js +61 -0
  25. package/src/client-graph/boundary-plugin.d.ts +0 -20
  26. package/src/client-graph/boundary-plugin.js +16 -98
  27. package/src/client-graph/reachability-analyzer.d.ts +4 -36
  28. package/src/client-graph/reachability-analyzer.js +23 -483
  29. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  30. package/src/client-graph/reachability-client-roots.js +59 -0
  31. package/src/client-graph/reachability-export-names.d.ts +5 -0
  32. package/src/client-graph/reachability-export-names.js +34 -0
  33. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  34. package/src/client-graph/reachability-fallback-roots.js +71 -0
  35. package/src/client-graph/reachability-preload.d.ts +10 -0
  36. package/src/client-graph/reachability-preload.js +30 -0
  37. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  38. package/src/client-graph/reachability-top-level-index.js +93 -0
  39. package/src/client-graph/reachability-traverse.d.ts +7 -0
  40. package/src/client-graph/reachability-traverse.js +201 -0
  41. package/src/client-graph/specifier-classification.d.ts +3 -2
  42. package/src/client-graph/specifier-classification.js +6 -2
  43. package/src/content/collection-component-cache.d.ts +25 -0
  44. package/src/content/collection-component-cache.js +62 -0
  45. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  46. package/src/hmr/hmr-strategy-process.js +83 -0
  47. package/src/hmr/hmr-strategy.d.ts +3 -0
  48. package/src/hmr/hmr-strategy.js +47 -86
  49. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +1 -0
  50. package/src/hmr/react-hmr-dev-transform-plugins.js +4 -1
  51. package/src/hydration/browser/island-hydration.d.ts +82 -0
  52. package/src/hydration/browser/island-hydration.js +247 -0
  53. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  54. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  55. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  56. package/src/hydration/browser/page-hydration-module.js +17 -0
  57. package/src/hydration/browser/page-hydration.d.ts +54 -0
  58. package/src/hydration/browser/page-hydration.js +177 -0
  59. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  60. package/src/hydration/hydration-asset.d.ts +21 -1
  61. package/src/hydration/hydration-asset.js +54 -24
  62. package/src/hydration/hydration-lifecycle.test.browser.d.ts +1 -0
  63. package/src/hydration/hydration-lifecycle.test.browser.js +409 -0
  64. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  65. package/src/hydration/hydration-page-entry-source.js +87 -0
  66. package/src/hydration/hydration-script-compiler.d.ts +48 -0
  67. package/src/hydration/hydration-script-compiler.js +213 -0
  68. package/src/hydration/page-data-reader.d.ts +0 -14
  69. package/src/hydration/page-data-reader.js +1 -47
  70. package/src/mdx/mdx-loader-plugin.d.ts +5 -1
  71. package/src/mdx/mdx-loader-plugin.js +4 -2
  72. package/src/plugin/react.plugin.js +8 -1
  73. package/src/plugin/react.types.d.ts +11 -2
  74. package/src/render/component-ssr.d.ts +17 -0
  75. package/src/render/component-ssr.js +19 -1
  76. package/src/render/react-renderer.d.ts +2 -1
  77. package/src/render/react-renderer.js +5 -1
  78. package/src/render/unified-layout-composition.d.ts +2 -0
  79. package/src/render/unified-layout-composition.js +5 -1
  80. package/src/hydration/hydration-scripts.d.ts +0 -104
  81. package/src/hydration/hydration-scripts.js +0 -483
  82. package/src/hydration/hydration-scripts.test.browser.js +0 -199
  83. /package/src/hydration/{hydration-scripts.test.browser.d.ts → compiled-page-hydration-options.js} +0 -0
@@ -0,0 +1,213 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { rolldown } from 'rolldown';
3
+ const ISLAND_BOOTSTRAP_ID = '\0ecopages-react-island-bootstrap';
4
+ const PAGE_BOOTSTRAP_ID = '\0ecopages-react-page-bootstrap';
5
+ const PAGE_HYDRATION_MODULE_ID = '\0ecopages-react-page-hydration-module';
6
+ const PAGE_HYDRATION_HMR_ID = '\0ecopages-react-page-hydration-hmr';
7
+ const PAGE_DATA_READER_ID = '\0ecopages-react-page-data-reader';
8
+ const PAGE_DATA_MANIFEST_ID = '\0ecopages-react-page-data-manifest';
9
+ import { createPageEntrySource } from './hydration-page-entry-source.js';
10
+ /** Serializes every compilation input so source/config changes cannot reuse stale output. */
11
+ function getCacheKey(options) {
12
+ return JSON.stringify(options);
13
+ }
14
+ /**
15
+ * Creates the small Island Host entry that imports application modules and
16
+ * delegates lifecycle behavior to the typed browser bootstrap.
17
+ */
18
+ function createEntrySource(options) {
19
+ const hmrSource = options.hmrEnabled
20
+ ? `registerIslandHmr(configuration, (url) => import(url), ${JSON.stringify(options.importPath)});`
21
+ : '';
22
+ return `
23
+ import { hydrateRoot } from ${JSON.stringify(options.reactDomClientImportPath)};
24
+ import { createElement, useEffect } from ${JSON.stringify(options.reactImportPath)};
25
+ import * as ComponentModule from ${JSON.stringify(options.importPath)};
26
+ import { getIslandHydrationRuntime, mountIslands, registerIslandHmr } from ${JSON.stringify(ISLAND_BOOTSTRAP_ID)};
27
+
28
+ const configuration = {
29
+ targetSelector: ${JSON.stringify(options.targetSelector)},
30
+ componentModule: ComponentModule,
31
+ componentRef: ${JSON.stringify(options.componentRef ?? '')},
32
+ componentFile: ${JSON.stringify(options.componentFile ?? '')},
33
+ scriptId: ${JSON.stringify(options.scriptId)},
34
+ runtime: { hydrateRoot, createElement, useEffect },
35
+ runtimeState: getIslandHydrationRuntime()
36
+ };
37
+ const mount = () => mountIslands(configuration);
38
+ ${hmrSource}
39
+ document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", mount, { once: true }) : mount();
40
+ `;
41
+ }
42
+ /**
43
+ * Resolves framework browser sources from repository TypeScript or published
44
+ * JavaScript files while keeping application and vendor modules external.
45
+ */
46
+ function createBootstrapPlugin() {
47
+ const sourcePaths = new Map([
48
+ [ISLAND_BOOTSTRAP_ID, ['island-hydration.ts', 'island-hydration.js']],
49
+ [PAGE_BOOTSTRAP_ID, ['page-hydration.ts', 'page-hydration.js']],
50
+ [PAGE_HYDRATION_MODULE_ID, ['page-hydration-module.ts', 'page-hydration-module.js']],
51
+ [PAGE_HYDRATION_HMR_ID, ['page-hydration-hmr.ts', 'page-hydration-hmr.js']],
52
+ [PAGE_DATA_READER_ID, ['../page-data-reader.js', '../page-data-reader.js']],
53
+ ]);
54
+ const readBootstrapSource = (id) => {
55
+ const candidates = sourcePaths.get(id);
56
+ if (!candidates)
57
+ throw new Error(`Unknown hydration bootstrap module: ${id}`);
58
+ for (const relativePath of candidates) {
59
+ try {
60
+ return readFileSync(new URL(`./browser/${relativePath}`, import.meta.url), 'utf8');
61
+ }
62
+ catch {
63
+ continue;
64
+ }
65
+ }
66
+ throw new Error(`Unable to locate hydration bootstrap source for ${id}`);
67
+ };
68
+ const pageBootstrapRelativeImports = new Map([
69
+ ['./page-hydration-module.js', PAGE_HYDRATION_MODULE_ID],
70
+ ['./page-hydration-hmr.js', PAGE_HYDRATION_HMR_ID],
71
+ ]);
72
+ return {
73
+ name: 'ecopages-react-hydration-bootstrap',
74
+ resolveId(source, importer) {
75
+ if (sourcePaths.has(source))
76
+ return source;
77
+ if (importer === PAGE_DATA_READER_ID && source === './page-data-manifest.js') {
78
+ return PAGE_DATA_MANIFEST_ID;
79
+ }
80
+ if (importer && pageBootstrapRelativeImports.has(source)) {
81
+ if (importer === PAGE_BOOTSTRAP_ID || importer === PAGE_HYDRATION_HMR_ID) {
82
+ return pageBootstrapRelativeImports.get(source);
83
+ }
84
+ }
85
+ return undefined;
86
+ },
87
+ load(id) {
88
+ if (id === PAGE_DATA_MANIFEST_ID) {
89
+ return {
90
+ code: readFileSync(new URL('./page-data-manifest.js', import.meta.url), 'utf8'),
91
+ moduleType: 'ts',
92
+ };
93
+ }
94
+ if (!sourcePaths.has(id))
95
+ return undefined;
96
+ return { code: readBootstrapSource(id), moduleType: 'ts' };
97
+ },
98
+ };
99
+ }
100
+ /** Bundles one virtual entry and closes the Rolldown bundle after generation. */
101
+ async function compileEntry(options) {
102
+ const bundle = await rolldown({
103
+ input: options.entryId,
104
+ plugins: [
105
+ {
106
+ name: 'ecopages-react-entry',
107
+ resolveId(source) {
108
+ return source === options.entryId ? source : undefined;
109
+ },
110
+ load(id) {
111
+ return id === options.entryId ? { code: options.entrySource, moduleType: 'js' } : undefined;
112
+ },
113
+ },
114
+ createBootstrapPlugin(),
115
+ ],
116
+ external: options.external,
117
+ transform: { target: 'es2021' },
118
+ });
119
+ try {
120
+ const generated = await bundle.generate({ format: 'esm', minify: options.minify });
121
+ const chunk = generated.output.find((output) => output.type === 'chunk');
122
+ if (!chunk || !('code' in chunk))
123
+ throw new Error(options.errorMessage);
124
+ return chunk.code ?? '';
125
+ }
126
+ finally {
127
+ await bundle.close();
128
+ }
129
+ }
130
+ /** Compiles an Island Host entry using the shared virtual-entry pipeline. */
131
+ function compileIsland(options) {
132
+ return compileEntry({
133
+ entryId: 'virtual:ecopages-react-island-entry',
134
+ entrySource: createEntrySource(options),
135
+ external: [options.importPath, options.reactImportPath, options.reactDomClientImportPath],
136
+ minify: options.minify,
137
+ errorMessage: 'React hydration compiler emitted no JavaScript chunk',
138
+ });
139
+ }
140
+ /** Compiles a Page entry using the shared virtual-entry pipeline. */
141
+ function compilePage(options) {
142
+ return compileEntry({
143
+ entryId: 'virtual:ecopages-react-page-entry',
144
+ entrySource: createPageEntrySource(options),
145
+ external: [
146
+ options.importPath,
147
+ options.reactImportPath,
148
+ options.reactDomClientImportPath,
149
+ options.routerImportPath,
150
+ options.layoutComposeImportPath,
151
+ options.pageLayoutNormalizationImportPath,
152
+ ].filter((value) => Boolean(value)),
153
+ minify: options.minify,
154
+ errorMessage: 'React page hydration compiler emitted no JavaScript chunk',
155
+ });
156
+ }
157
+ /** Caches in-flight and completed compilations while evicting rejected work. */
158
+ class CompilationCache {
159
+ entries = new Map();
160
+ /** Returns a cached compilation or starts exactly one compilation for the key. */
161
+ getOrCompile(key, factory) {
162
+ const cached = this.entries.get(key);
163
+ if (cached)
164
+ return cached;
165
+ const pending = factory();
166
+ this.entries.set(key, pending);
167
+ pending.then(() => undefined, () => {
168
+ if (this.entries.get(key) === pending)
169
+ this.entries.delete(key);
170
+ });
171
+ return pending;
172
+ }
173
+ }
174
+ /**
175
+ * Compiles the editable React Island Host lifecycle into a browser ESM string.
176
+ *
177
+ * @remarks
178
+ * Compilation is cached by the complete entry configuration. Rejected promises
179
+ * are removed so a transient filesystem or bundler error can recover.
180
+ */
181
+ export class IslandHydrationScriptCompiler {
182
+ compilationCache = new CompilationCache();
183
+ /**
184
+ * Compiles and caches one readable or minified Island Host entry.
185
+ *
186
+ * @param options - Complete entry imports, selector, identity, and output mode.
187
+ * @returns A browser ESM source string.
188
+ */
189
+ compile(options) {
190
+ const key = getCacheKey(options);
191
+ return this.compilationCache.getOrCompile(key, () => compileIsland(options));
192
+ }
193
+ }
194
+ /**
195
+ * Compiles editable Page lifecycle modules into browser ESM strings.
196
+ *
197
+ * @remarks
198
+ * The cache belongs to the service instance, allowing development restarts to
199
+ * discard framework-source changes without sharing stale output globally.
200
+ */
201
+ export class PageHydrationScriptCompiler {
202
+ compilationCache = new CompilationCache();
203
+ /**
204
+ * Compiles and caches one readable or minified Page entry.
205
+ *
206
+ * @param options - Complete page imports, router contract, and output mode.
207
+ * @returns A browser ESM source string.
208
+ */
209
+ compile(options) {
210
+ const key = getCacheKey(options);
211
+ return this.compilationCache.getOrCompile(key, () => compilePage(options));
212
+ }
213
+ }
@@ -15,17 +15,3 @@ export declare function readPageDataDocument(): ReadPageDataDocumentResult;
15
15
  * Returns page props from `__ECO_PAGE_DATA__` for hydration and HMR handlers.
16
16
  */
17
17
  export declare function getPageDataFromDocument(): EcoPageDataProps;
18
- /**
19
- * Inlined browser bootstrap for generated hydration scripts.
20
- *
21
- * @remarks
22
- * Hydration and HMR entry modules are evaluated as native browser ESM. Bare
23
- * package imports such as `@ecopages/react/page-data-reader` are not resolvable
24
- * there, so the reader algorithm is embedded. Keep this string aligned with
25
- * {@link readPageDataDocument} / {@link getPageDataFromDocument}.
26
- */
27
- export declare function getDevPageDataReaderBootstrapSource(): string;
28
- /**
29
- * Minified equivalent of {@link getDevPageDataReaderBootstrapSource}.
30
- */
31
- export declare function getProdPageDataReaderBootstrapSource(): string;
@@ -1,4 +1,4 @@
1
- import { ECO_PAGE_DATA_SCHEMA_VERSION, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, } from './page-data-manifest.js';
1
+ import { resolveEcoPageDataModuleUrl, resolveEcoPageDataProps } from './page-data-manifest.js';
2
2
  /**
3
3
  * Reads `__ECO_PAGE_DATA__`, supporting both v1 envelopes and legacy flat props.
4
4
  *
@@ -29,49 +29,3 @@ export function readPageDataDocument() {
29
29
  export function getPageDataFromDocument() {
30
30
  return readPageDataDocument().props;
31
31
  }
32
- /**
33
- * Inlined browser bootstrap for generated hydration scripts.
34
- *
35
- * @remarks
36
- * Hydration and HMR entry modules are evaluated as native browser ESM. Bare
37
- * package imports such as `@ecopages/react/page-data-reader` are not resolvable
38
- * there, so the reader algorithm is embedded. Keep this string aligned with
39
- * {@link readPageDataDocument} / {@link getPageDataFromDocument}.
40
- */
41
- export function getDevPageDataReaderBootstrapSource() {
42
- return `const readPageDataDocument = () => {
43
- const el = document.getElementById("__ECO_PAGE_DATA__");
44
- if (!el?.textContent) {
45
- return { props: {} };
46
- }
47
- try {
48
- const parsed = JSON.parse(el.textContent);
49
- if (
50
- parsed &&
51
- parsed.schemaVersion === ${ECO_PAGE_DATA_SCHEMA_VERSION} &&
52
- parsed.navigationOwner === "react-router" &&
53
- typeof parsed.moduleUrl === "string" &&
54
- parsed.props &&
55
- typeof parsed.props === "object" &&
56
- !Array.isArray(parsed.props)
57
- ) {
58
- return { moduleUrl: parsed.moduleUrl, props: parsed.props };
59
- }
60
- if (parsed && typeof parsed === "object" && typeof parsed.schemaVersion === "number") {
61
- return { props: {} };
62
- }
63
- return {
64
- props: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {},
65
- };
66
- } catch {
67
- return { props: {} };
68
- }
69
- };
70
- const getPageData = () => readPageDataDocument().props;`;
71
- }
72
- /**
73
- * Minified equivalent of {@link getDevPageDataReaderBootstrapSource}.
74
- */
75
- export function getProdPageDataReaderBootstrapSource() {
76
- return `const rd=()=>{const e=document.getElementById("__ECO_PAGE_DATA__");if(!e?.textContent)return{props:{}};try{const p=JSON.parse(e.textContent);if(p&&p.schemaVersion===${ECO_PAGE_DATA_SCHEMA_VERSION}&&p.navigationOwner==="react-router"&&typeof p.moduleUrl==="string"&&p.props&&typeof p.props==="object"&&!Array.isArray(p.props))return{moduleUrl:p.moduleUrl,props:p.props};if(p&&typeof p==="object"&&typeof p.schemaVersion==="number")return{props:{}};return{props:p&&typeof p==="object"&&!Array.isArray(p)?p:{}}}catch{return{props:{}}}};const gd=()=>rd().props;`;
77
- }
@@ -1,2 +1,6 @@
1
1
  import type { CompileOptions } from '@mdx-js/mdx';
2
- export declare function createReactMdxLoaderPlugin(compilerOptions?: CompileOptions): import("@ecopages/core/build/build-types").EcoBuildPlugin;
2
+ export interface CreateReactMdxLoaderPluginOptions {
3
+ compilerOptions?: CompileOptions;
4
+ projectRoot: string;
5
+ }
6
+ export declare function createReactMdxLoaderPlugin(options: CreateReactMdxLoaderPluginOptions): import("@ecopages/core/build/build-types").EcoBuildPlugin;
@@ -1,8 +1,10 @@
1
1
  import { createMdxLoaderPlugin as createMdxLoaderPluginCore } from '@ecopages/mdx/core';
2
- export function createReactMdxLoaderPlugin(compilerOptions) {
2
+ export function createReactMdxLoaderPlugin(options) {
3
3
  return createMdxLoaderPluginCore({
4
4
  name: 'react-mdx-loader',
5
- compilerOptions,
5
+ integrationName: 'react',
6
+ compilerOptions: options.compilerOptions,
6
7
  defaultMdExtensions: [],
8
+ projectRoot: options.projectRoot,
7
9
  });
8
10
  }
@@ -175,7 +175,13 @@ export class ReactPlugin extends IntegrationPlugin {
175
175
  if (!this.mdxEnabled || !this.mdxCompilerOptions || this.mdxLoaderPlugin) {
176
176
  return;
177
177
  }
178
- this.mdxLoaderPlugin = createReactMdxLoaderPlugin(this.mdxCompilerOptions);
178
+ if (!this.appConfig?.rootDir) {
179
+ throw new Error('[ReactPlugin] Cannot create MDX loader: appConfig.rootDir is required.');
180
+ }
181
+ this.mdxLoaderPlugin = createReactMdxLoaderPlugin({
182
+ compilerOptions: this.mdxCompilerOptions,
183
+ projectRoot: this.appConfig.rootDir,
184
+ });
179
185
  }
180
186
  /**
181
187
  * Prepares React's build-facing loader contributions before config build seals
@@ -220,6 +226,7 @@ export class ReactPlugin extends IntegrationPlugin {
220
226
  if (!this.hmrStrategy) {
221
227
  this.hmrStrategy = new ReactHmrStrategy({
222
228
  context: this.hmrManager.getDefaultContext(),
229
+ projectRoot: this.appConfig.rootDir,
223
230
  pageMetadataCache: this.hmrPageMetadataCache,
224
231
  runtimeManifest: this.runtimeBundleService.getRuntimeManifest('development'),
225
232
  mdxCompilerOptions: this.mdxCompilerOptions,
@@ -89,6 +89,11 @@ export type ReactPluginOptions = {
89
89
  * `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
90
90
  * It does not vendor every npm dependency reachable from shell or page UI.
91
91
  *
92
+ * Singleton libraries (MobX, Redux, TanStack Query, audio engines) must be
93
+ * peer dependencies in shared state/UI packages and registered here explicitly
94
+ * when page code imports them outside the layout graph. List each singleton in
95
+ * `externals` on library vendors that import it so one shared vendor URL is used.
96
+ *
92
97
  * Layouts that mount shared runtime state should set `runtimeProvider: true` in
93
98
  * `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
94
99
  * vendor every reachable npm package in that layout graph. When no layout opts
@@ -108,8 +113,12 @@ export type ReactPluginOptions = {
108
113
  * ```
109
114
  *
110
115
  * Manual entries override auto-discovered entries for the same specifier.
111
- * Subpath imports such as `@acme/ui/button` dedupe to the registered package
112
- * root vendor URL when `@acme/ui` is configured here or auto-discovered.
116
+ * Discovery normalizes package subpaths to package roots when collecting
117
+ * vendors. Import rewrite matches exact specifiers only — register subpaths
118
+ * separately in `runtimeModules` when page code imports them directly.
119
+ *
120
+ * `externals` on a library vendor must already be shared vendors (React, the
121
+ * router, or another `runtimeModules` specifier). Unmapped externals throw.
113
122
  *
114
123
  * @example Advanced vendor config
115
124
  * ```ts
@@ -92,6 +92,19 @@ export declare function renderForeignComponentWithSerializedHtml(options: {
92
92
  html: string;
93
93
  }>;
94
94
  }): Promise<ComponentRenderResult>;
95
+ /**
96
+ * Renders a React Component and, when eligible, emits its server Island Host.
97
+ *
98
+ * @remarks
99
+ * A host is emitted only for a single-root component with an instance identity,
100
+ * resolved assets, and no already-resolved child HTML. The host carries the
101
+ * framework attributes while its existing children remain available for
102
+ * `hydrateRoot`; fragment, text-only, and empty output stay outside this
103
+ * eligibility policy.
104
+ *
105
+ * @param options - Rendering inputs, foreign-subtree state, and hydration asset services.
106
+ * @returns SSR HTML, root metadata, and deduplicated browser assets.
107
+ */
95
108
  export declare function renderReactManagedComponent(options: {
96
109
  input: ComponentRenderInput;
97
110
  runtimeContext: ReactForeignSubtreeResolutionContext | undefined;
@@ -107,6 +120,10 @@ export declare function renderReactManagedComponent(options: {
107
120
  hydrationAssetService: HydrationAssetService;
108
121
  canBuildIslandAssets: boolean;
109
122
  }): Promise<ComponentRenderResult>;
123
+ /**
124
+ * Creates the per-render state used to resolve foreign child subtrees without
125
+ * leaking renderer caches or instance identity into another render.
126
+ */
110
127
  export declare function createForeignSubtreeRuntimeContext(options: {
111
128
  rendererCache: Map<string, IntegrationRenderer<any>>;
112
129
  componentInstanceScope?: string;
@@ -123,6 +123,19 @@ export async function renderForeignComponentWithSerializedHtml(options) {
123
123
  assets: mergedAssets.length > 0 ? mergedAssets : undefined,
124
124
  };
125
125
  }
126
+ /**
127
+ * Renders a React Component and, when eligible, emits its server Island Host.
128
+ *
129
+ * @remarks
130
+ * A host is emitted only for a single-root component with an instance identity,
131
+ * resolved assets, and no already-resolved child HTML. The host carries the
132
+ * framework attributes while its existing children remain available for
133
+ * `hydrateRoot`; fragment, text-only, and empty output stay outside this
134
+ * eligibility policy.
135
+ *
136
+ * @param options - Rendering inputs, foreign-subtree state, and hydration asset services.
137
+ * @returns SSR HTML, root metadata, and deduplicated browser assets.
138
+ */
126
139
  export async function renderReactManagedComponent(options) {
127
140
  const { input, runtimeContext, runtime, integrationName, normalizeUnresolvedMarkerArtifactHtml, resolveQueuedForeignSubtreeHtml, getRootTagName, dedupeProcessedAssets, hydrationAssetService, canBuildIslandAssets, } = options;
128
141
  const componentConfig = input.component.config;
@@ -157,17 +170,22 @@ export async function renderReactManagedComponent(options) {
157
170
  componentKey: getIslandComponentKey(componentFile, componentConfig),
158
171
  props: buildHydrationProps(input.props),
159
172
  });
173
+ html = `<eco-island style="display:contents">${html}</eco-island>`;
160
174
  }
161
175
  const mergedAssets = dedupeProcessedAssets([...(assets ?? []), ...queuedForeignSubtreeResolution.assets]);
162
176
  return {
163
177
  html,
164
178
  canAttachAttributes,
165
- rootTag,
179
+ rootTag: rootAttributes ? 'eco-island' : rootTag,
166
180
  integrationName,
167
181
  rootAttributes,
168
182
  assets: mergedAssets.length > 0 ? mergedAssets : undefined,
169
183
  };
170
184
  }
185
+ /**
186
+ * Creates the per-render state used to resolve foreign child subtrees without
187
+ * leaking renderer caches or instance identity into another render.
188
+ */
171
189
  export function createForeignSubtreeRuntimeContext(options) {
172
190
  return {
173
191
  rendererCache: options.rendererCache,
@@ -109,6 +109,7 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
109
109
  pageProps: Record<string, unknown>;
110
110
  documentProps?: Record<string, unknown>;
111
111
  transformDocumentHtml?: (html: string) => string;
112
+ foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
112
113
  }): Promise<string>;
113
114
  /**
114
115
  * Renders a full route response for the filesystem page pipeline.
@@ -118,7 +119,7 @@ export declare class ReactRenderer extends IntegrationRenderer<ReactNode> {
118
119
  * serialize only the browser-safe page payload, compose the mixed React/non-
119
120
  * React shell tree, and hand the result back as a document body.
120
121
  */
121
- render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, pagePackage, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
122
+ render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, pagePackage, resolvedPageDependencyComponents, }: IntegrationRendererRenderOptions<ReactNode>): Promise<RouteRendererBody>;
122
123
  protected getHtmlDocumentContributions(options: HtmlDocumentContributionContext<ReactNode>): HtmlDocumentContribution[] | undefined;
123
124
  protected getDocumentAttributes(): Record<string, string> | undefined;
124
125
  protected renderViewWithDocumentShell<P>(input: {
@@ -279,7 +279,9 @@ export class ReactRenderer extends IntegrationRenderer {
279
279
  const composeChildren = resolveComposeChildren({
280
280
  page: input.page,
281
281
  shellLayouts,
282
+ foreignChildRoots: input.foreignChildRoots,
282
283
  reactIntegrationName: this.name,
284
+ hasForeignChildDescendants: (component, roots) => this.hasForeignChildDescendants(component, roots),
283
285
  composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context),
284
286
  });
285
287
  return renderPageDocumentShell({
@@ -298,7 +300,7 @@ export class ReactRenderer extends IntegrationRenderer {
298
300
  * serialize only the browser-safe page payload, compose the mixed React/non-
299
301
  * React shell tree, and hand the result back as a document body.
300
302
  */
301
- async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, pagePackage, }) {
303
+ async render({ params, query, props, locals, pageLocals, metadata, Page, Layout, layoutEntries, HtmlTemplate, pageProps, pagePackage, resolvedPageDependencyComponents, }) {
302
304
  try {
303
305
  const pageModuleUrl = this.pagePayloadService.resolvePageModuleUrl(pagePackage, {
304
306
  routerEnabled: Boolean(this.routerAdapter),
@@ -326,6 +328,7 @@ export class ReactRenderer extends IntegrationRenderer {
326
328
  metadata,
327
329
  pageProps: allPageProps,
328
330
  documentProps: pageModuleUrl ? { pageModuleUrl } : undefined,
331
+ foreignChildRoots: resolvedPageDependencyComponents,
329
332
  });
330
333
  }
331
334
  catch (error) {
@@ -387,6 +390,7 @@ export class ReactRenderer extends IntegrationRenderer {
387
390
  page: { component: input.view, props: normalizedProps },
388
391
  shellLayouts,
389
392
  reactIntegrationName: this.name,
393
+ hasForeignChildDescendants: (component, roots) => this.hasForeignChildDescendants(component, roots),
390
394
  composeChildren: (page, context) => this.composeReactLayoutPageChildrenForShell(page, context),
391
395
  });
392
396
  const { documentHtml } = await composeDocumentShell({
@@ -29,7 +29,9 @@ export declare function resolveComposeChildren(options: {
29
29
  props: Record<string, unknown>;
30
30
  };
31
31
  shellLayouts: DocumentShellLayoutInput[];
32
+ foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
32
33
  reactIntegrationName: string;
34
+ hasForeignChildDescendants: (component: EcoComponent, foreignChildRoots?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>) => boolean;
33
35
  composeChildren: (page: {
34
36
  component: EcoComponent;
35
37
  props: Record<string, unknown>;
@@ -31,7 +31,7 @@ export function shouldUseUnifiedReactLayoutComposition(options) {
31
31
  return layoutComponents.every((component) => isReactManagedComponent(component, reactIntegrationName));
32
32
  }
33
33
  export function resolveComposeChildren(options) {
34
- const { page, shellLayouts, reactIntegrationName, composeChildren } = options;
34
+ const { page, shellLayouts, foreignChildRoots, reactIntegrationName, hasForeignChildDescendants, composeChildren } = options;
35
35
  if (!shouldUseUnifiedReactLayoutComposition({
36
36
  page: page.component,
37
37
  shellLayouts,
@@ -39,6 +39,10 @@ export function resolveComposeChildren(options) {
39
39
  })) {
40
40
  return undefined;
41
41
  }
42
+ if (hasForeignChildDescendants(page.component, foreignChildRoots) ||
43
+ shellLayouts.some((layout) => hasForeignChildDescendants(layout.component))) {
44
+ return undefined;
45
+ }
42
46
  return (context) => composeChildren(page, context);
43
47
  }
44
48
  export async function composeReactLayoutPageChildren(options) {
@@ -1,104 +0,0 @@
1
- /**
2
- * Hydration script generators for React pages.
3
- * These functions create the page entry modules that hydrate React routes.
4
- * @module
5
- */
6
- import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
7
- /**
8
- * Options for generating a hydration script.
9
- */
10
- export type HydrationScriptOptions = {
11
- /** The module path imported by the page entry module. */
12
- importPath: string;
13
- /** Browser expression that resolves to the page module URL the router should import. */
14
- pageModuleUrlExpression?: string;
15
- /** Stable id of the page entry script tag in the document. */
16
- scriptId: string;
17
- /** Direct import path for React runtime module */
18
- reactImportPath: string;
19
- /** Direct import path for react-dom/client runtime module */
20
- reactDomClientImportPath: string;
21
- /** Direct import path for router runtime module */
22
- routerImportPath?: string;
23
- /**
24
- * When true, emit HMR registration and hot-reload handlers.
25
- *
26
- * @remarks
27
- * HMR page bootstraps stay unbundled and evaluate as native browser ESM.
28
- * Callers must supply browser-resolvable import paths (shared vendor URLs)
29
- * so generated source does not emit bare `@ecopages/*` imports. When false,
30
- * this generator emits the same readable bootstrap without HMR hooks.
31
- */
32
- hmrEnabled: boolean;
33
- /** Whether the source file is an MDX file */
34
- isMdx: boolean;
35
- /** Optional router adapter for SPA navigation */
36
- router?: ReactRouterAdapter;
37
- /**
38
- * Import path for shared layout composition helper.
39
- *
40
- * @remarks
41
- * Required so callers (not this generator) decide vendor URL vs bare package.
42
- */
43
- layoutComposeImportPath: string;
44
- /**
45
- * Import path for MDX page layout normalization helper.
46
- *
47
- * @remarks
48
- * Required so callers (not this generator) decide vendor URL vs bare package.
49
- */
50
- pageLayoutNormalizationImportPath: string;
51
- /**
52
- * Optional import path for the page-data reader.
53
- *
54
- * @remarks
55
- * When omitted, hydration scripts inline the reader so native browser ESM /
56
- * HMR entry evaluation does not depend on bare `@ecopages/react/*` imports.
57
- * Browser unit tests that execute `data:` scripts may still pass a resolvable URL.
58
- */
59
- pageDataReaderImportPath?: string;
60
- };
61
- export type IslandHydrationScriptOptions = {
62
- /** Bundled browser module path for the island component. */
63
- importPath: string;
64
- /** Stable id of the island bootstrap script tag in the document. */
65
- scriptId: string;
66
- /** Browser import path for React runtime. */
67
- reactImportPath: string;
68
- /** Browser import path for react-dom/client runtime. */
69
- reactDomClientImportPath: string;
70
- /** Selector that resolves to all SSR root elements for this island component. */
71
- targetSelector: string;
72
- /** Optional stable component id used to resolve named exports reliably. */
73
- componentRef?: string;
74
- /** Optional source file hint used as fallback for component resolution. */
75
- componentFile?: string;
76
- /**
77
- * When true, emit a compact source string.
78
- *
79
- * @remarks
80
- * Island bootstraps use `bundle: false`, so compact output must be generated
81
- * here rather than delegated to the bundler.
82
- */
83
- minify: boolean;
84
- /**
85
- * When true, register an HMR handler that hot-imports the dev transform module.
86
- */
87
- hmrEnabled?: boolean;
88
- };
89
- /**
90
- * Creates a page hydration entry module.
91
- *
92
- * @remarks
93
- * Always emits readable source. Production page assets set `bundle: true` so
94
- * core's content-script processor minifies the result. Do not hand-minify here.
95
- */
96
- export declare function createHydrationScript(options: HydrationScriptOptions): string;
97
- /**
98
- * Creates the client bootstrap for component-level React islands.
99
- *
100
- * @remarks
101
- * Island scripts use `bundle: false`, so compact output still needs a
102
- * handwritten string.
103
- */
104
- export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;