@ecopages/react 0.2.0-rc.6 → 0.2.0-rc.7
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.
- package/README.md +21 -4
- package/package.json +5 -4
- package/src/hydration/browser/island-hydration.d.ts +82 -0
- package/src/hydration/browser/island-hydration.js +247 -0
- package/src/hydration/browser/page-hydration.d.ts +70 -0
- package/src/hydration/browser/page-hydration.js +254 -0
- package/src/hydration/hydration-asset.d.ts +20 -1
- package/src/hydration/hydration-asset.js +42 -24
- package/src/hydration/hydration-lifecycle.test.browser.js +408 -0
- package/src/hydration/hydration-script-compiler.d.ts +66 -0
- package/src/hydration/hydration-script-compiler.js +268 -0
- package/src/hydration/page-data-reader.d.ts +0 -14
- package/src/hydration/page-data-reader.js +1 -47
- package/src/render/component-ssr.d.ts +17 -0
- package/src/render/component-ssr.js +19 -1
- package/src/render/react-renderer.d.ts +2 -1
- package/src/render/react-renderer.js +5 -1
- package/src/render/unified-layout-composition.d.ts +2 -0
- package/src/render/unified-layout-composition.js +5 -1
- package/src/hydration/hydration-scripts.d.ts +0 -112
- package/src/hydration/hydration-scripts.js +0 -517
- package/src/hydration/hydration-scripts.test.browser.js +0 -199
- /package/src/hydration/{hydration-scripts.test.browser.d.ts → hydration-lifecycle.test.browser.d.ts} +0 -0
|
@@ -0,0 +1,268 @@
|
|
|
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_DATA_READER_ID = '\0ecopages-react-page-data-reader';
|
|
6
|
+
const PAGE_DATA_MANIFEST_ID = '\0ecopages-react-page-data-manifest';
|
|
7
|
+
/** Serializes every compilation input so source/config changes cannot reuse stale output. */
|
|
8
|
+
function getCacheKey(options) {
|
|
9
|
+
return JSON.stringify(options);
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Creates the small Island Host entry that imports application modules and
|
|
13
|
+
* delegates lifecycle behavior to the typed browser bootstrap.
|
|
14
|
+
*/
|
|
15
|
+
function createEntrySource(options) {
|
|
16
|
+
const hmrSource = options.hmrEnabled
|
|
17
|
+
? `registerIslandHmr(configuration, (url) => import(url), ${JSON.stringify(options.importPath)});`
|
|
18
|
+
: '';
|
|
19
|
+
return `
|
|
20
|
+
import { hydrateRoot } from ${JSON.stringify(options.reactDomClientImportPath)};
|
|
21
|
+
import { createElement, useEffect } from ${JSON.stringify(options.reactImportPath)};
|
|
22
|
+
import * as ComponentModule from ${JSON.stringify(options.importPath)};
|
|
23
|
+
import { getIslandHydrationRuntime, mountIslands, registerIslandHmr } from ${JSON.stringify(ISLAND_BOOTSTRAP_ID)};
|
|
24
|
+
|
|
25
|
+
const configuration = {
|
|
26
|
+
targetSelector: ${JSON.stringify(options.targetSelector)},
|
|
27
|
+
componentModule: ComponentModule,
|
|
28
|
+
componentRef: ${JSON.stringify(options.componentRef ?? '')},
|
|
29
|
+
componentFile: ${JSON.stringify(options.componentFile ?? '')},
|
|
30
|
+
scriptId: ${JSON.stringify(options.scriptId)},
|
|
31
|
+
runtime: { hydrateRoot, createElement, useEffect },
|
|
32
|
+
runtimeState: getIslandHydrationRuntime()
|
|
33
|
+
};
|
|
34
|
+
const mount = () => mountIslands(configuration);
|
|
35
|
+
${hmrSource}
|
|
36
|
+
document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", mount, { once: true }) : mount();
|
|
37
|
+
`;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Creates the Page entry contract consumed by the browser lifecycle.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* Router adapters provide their tree expression as an intentional integration
|
|
44
|
+
* boundary. Everything else—module normalization, page-data reading, HMR, and
|
|
45
|
+
* root ownership—belongs to the shared browser module.
|
|
46
|
+
*/
|
|
47
|
+
function createPageEntrySource(options) {
|
|
48
|
+
if (options.routerComponents && !options.routerImportPath) {
|
|
49
|
+
throw new Error('routerImportPath is required when router components are configured');
|
|
50
|
+
}
|
|
51
|
+
if (options.routerComponents && !options.routerPropsExpression) {
|
|
52
|
+
throw new Error('routerPropsExpression is required when router components are configured');
|
|
53
|
+
}
|
|
54
|
+
const pageImport = options.isMdx || options.hasPagePreload
|
|
55
|
+
? `import * as PageModule from ${JSON.stringify(options.importPath)};`
|
|
56
|
+
: `import Page from ${JSON.stringify(options.importPath)};`;
|
|
57
|
+
const initialPage = options.isMdx || options.hasPagePreload
|
|
58
|
+
? `const initialPage = resolvePageModule(PageModule, ${options.isMdx}, ${options.isMdx ? 'ensurePageConfigLayouts' : 'undefined'});`
|
|
59
|
+
: `const initialPage = resolvePageModule({ default: Page }, false);`;
|
|
60
|
+
const routerImports = options.routerComponents
|
|
61
|
+
? `import { ${options.routerComponents.router}, ${options.routerComponents.pageContent} } from ${JSON.stringify(options.routerImportPath)};`
|
|
62
|
+
: '';
|
|
63
|
+
const routerTree = options.routerComponents
|
|
64
|
+
? `const createTree = (Page, props) => {
|
|
65
|
+
const pageContent = createElement(${options.routerComponents.pageContent});
|
|
66
|
+
return createElement(${options.routerComponents.router}, ${options.routerPropsExpression}, pageContent);
|
|
67
|
+
};`
|
|
68
|
+
: 'const createTree = (Page, props) => composeLayoutPageTree(Page, props);';
|
|
69
|
+
const normalizationImport = options.isMdx
|
|
70
|
+
? `import { ensurePageConfigLayouts } from ${JSON.stringify(options.pageLayoutNormalizationImportPath)};`
|
|
71
|
+
: '';
|
|
72
|
+
const hmr = options.hmrEnabled
|
|
73
|
+
? `hmr: {
|
|
74
|
+
importPath: ${JSON.stringify(options.importPath)},
|
|
75
|
+
${options.routerComponents ? 'getLayoutStack: (Page) => (Page.config?.layouts ?? []).map((layout) => layout?.config?.identity?.file ?? "").join("|")' : ''}
|
|
76
|
+
},`
|
|
77
|
+
: '';
|
|
78
|
+
return `
|
|
79
|
+
import { hydrateRoot } from ${JSON.stringify(options.reactDomClientImportPath)};
|
|
80
|
+
import { createElement } from ${JSON.stringify(options.reactImportPath)};
|
|
81
|
+
import { resolvePageModule, startPageHydration } from ${JSON.stringify(PAGE_BOOTSTRAP_ID)};
|
|
82
|
+
import { readPageDataDocument, getPageDataFromDocument } from ${JSON.stringify(PAGE_DATA_READER_ID)};
|
|
83
|
+
${options.routerComponents ? '' : `import { composeLayoutPageTree } from ${JSON.stringify(options.layoutComposeImportPath)};`}
|
|
84
|
+
${routerImports}
|
|
85
|
+
${normalizationImport}
|
|
86
|
+
${pageImport}
|
|
87
|
+
const pageModuleUrl = ${options.pageModuleUrlExpression};
|
|
88
|
+
${initialPage}
|
|
89
|
+
${routerTree}
|
|
90
|
+
export default initialPage.Page;
|
|
91
|
+
${options.hasPagePreload ? 'export const preload = initialPage.preload;' : ''}
|
|
92
|
+
export const config = initialPage.Page.config;
|
|
93
|
+
startPageHydration({
|
|
94
|
+
scriptId: ${JSON.stringify(options.scriptId)},
|
|
95
|
+
pageModuleUrl,
|
|
96
|
+
Page: initialPage.Page,
|
|
97
|
+
pageDataReader: { readPageDataDocument, getPageDataFromDocument },
|
|
98
|
+
runtime: { hydrateRoot, createElement },
|
|
99
|
+
createTree,
|
|
100
|
+
hasRouter: ${Boolean(options.routerComponents)},
|
|
101
|
+
isMdx: ${options.isMdx},
|
|
102
|
+
${options.isMdx ? 'normalizePageConfig: ensurePageConfigLayouts,' : ''}
|
|
103
|
+
${options.hasPagePreload ? 'preload: initialPage.preload,' : ''}
|
|
104
|
+
${hmr}
|
|
105
|
+
});
|
|
106
|
+
`.trim();
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Resolves framework browser sources from repository TypeScript or published
|
|
110
|
+
* JavaScript files while keeping application and vendor modules external.
|
|
111
|
+
*/
|
|
112
|
+
function createBootstrapPlugin() {
|
|
113
|
+
const sourcePaths = new Map([
|
|
114
|
+
[ISLAND_BOOTSTRAP_ID, ['island-hydration.ts', 'island-hydration.js']],
|
|
115
|
+
[PAGE_BOOTSTRAP_ID, ['page-hydration.ts', 'page-hydration.js']],
|
|
116
|
+
[PAGE_DATA_READER_ID, ['../page-data-reader.js', '../page-data-reader.js']],
|
|
117
|
+
]);
|
|
118
|
+
const readBootstrapSource = (id) => {
|
|
119
|
+
const candidates = sourcePaths.get(id);
|
|
120
|
+
if (!candidates)
|
|
121
|
+
throw new Error(`Unknown hydration bootstrap module: ${id}`);
|
|
122
|
+
for (const relativePath of candidates) {
|
|
123
|
+
try {
|
|
124
|
+
return readFileSync(new URL(`./browser/${relativePath}`, import.meta.url), 'utf8');
|
|
125
|
+
}
|
|
126
|
+
catch {
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
throw new Error(`Unable to locate hydration bootstrap source for ${id}`);
|
|
131
|
+
};
|
|
132
|
+
return {
|
|
133
|
+
name: 'ecopages-react-hydration-bootstrap',
|
|
134
|
+
resolveId(source, importer) {
|
|
135
|
+
if (sourcePaths.has(source))
|
|
136
|
+
return source;
|
|
137
|
+
if (importer === PAGE_DATA_READER_ID && source === './page-data-manifest.js') {
|
|
138
|
+
return PAGE_DATA_MANIFEST_ID;
|
|
139
|
+
}
|
|
140
|
+
return undefined;
|
|
141
|
+
},
|
|
142
|
+
load(id) {
|
|
143
|
+
if (id === PAGE_DATA_MANIFEST_ID) {
|
|
144
|
+
return {
|
|
145
|
+
code: readFileSync(new URL('./page-data-manifest.js', import.meta.url), 'utf8'),
|
|
146
|
+
moduleType: 'ts',
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
if (!sourcePaths.has(id))
|
|
150
|
+
return undefined;
|
|
151
|
+
return { code: readBootstrapSource(id), moduleType: 'ts' };
|
|
152
|
+
},
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
/** Bundles one virtual entry and closes the Rolldown bundle after generation. */
|
|
156
|
+
async function compileEntry(options) {
|
|
157
|
+
const bundle = await rolldown({
|
|
158
|
+
input: options.entryId,
|
|
159
|
+
plugins: [
|
|
160
|
+
{
|
|
161
|
+
name: 'ecopages-react-entry',
|
|
162
|
+
resolveId(source) {
|
|
163
|
+
return source === options.entryId ? source : undefined;
|
|
164
|
+
},
|
|
165
|
+
load(id) {
|
|
166
|
+
return id === options.entryId ? { code: options.entrySource, moduleType: 'js' } : undefined;
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
createBootstrapPlugin(),
|
|
170
|
+
],
|
|
171
|
+
external: options.external,
|
|
172
|
+
transform: { target: 'es2021' },
|
|
173
|
+
});
|
|
174
|
+
try {
|
|
175
|
+
const generated = await bundle.generate({ format: 'esm', minify: options.minify });
|
|
176
|
+
const chunk = generated.output.find((output) => output.type === 'chunk');
|
|
177
|
+
if (!chunk || !('code' in chunk))
|
|
178
|
+
throw new Error(options.errorMessage);
|
|
179
|
+
return chunk.code ?? '';
|
|
180
|
+
}
|
|
181
|
+
finally {
|
|
182
|
+
await bundle.close();
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
/** Compiles an Island Host entry using the shared virtual-entry pipeline. */
|
|
186
|
+
function compileIsland(options) {
|
|
187
|
+
return compileEntry({
|
|
188
|
+
entryId: 'virtual:ecopages-react-island-entry',
|
|
189
|
+
entrySource: createEntrySource(options),
|
|
190
|
+
external: [options.importPath, options.reactImportPath, options.reactDomClientImportPath],
|
|
191
|
+
minify: options.minify,
|
|
192
|
+
errorMessage: 'React hydration compiler emitted no JavaScript chunk',
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
/** Compiles a Page entry using the shared virtual-entry pipeline. */
|
|
196
|
+
function compilePage(options) {
|
|
197
|
+
return compileEntry({
|
|
198
|
+
entryId: 'virtual:ecopages-react-page-entry',
|
|
199
|
+
entrySource: createPageEntrySource(options),
|
|
200
|
+
external: [
|
|
201
|
+
options.importPath,
|
|
202
|
+
options.reactImportPath,
|
|
203
|
+
options.reactDomClientImportPath,
|
|
204
|
+
options.routerImportPath,
|
|
205
|
+
options.layoutComposeImportPath,
|
|
206
|
+
options.pageLayoutNormalizationImportPath,
|
|
207
|
+
].filter((value) => Boolean(value)),
|
|
208
|
+
minify: options.minify,
|
|
209
|
+
errorMessage: 'React page hydration compiler emitted no JavaScript chunk',
|
|
210
|
+
});
|
|
211
|
+
}
|
|
212
|
+
/** Caches in-flight and completed compilations while evicting rejected work. */
|
|
213
|
+
class CompilationCache {
|
|
214
|
+
entries = new Map();
|
|
215
|
+
/** Returns a cached compilation or starts exactly one compilation for the key. */
|
|
216
|
+
getOrCompile(key, factory) {
|
|
217
|
+
const cached = this.entries.get(key);
|
|
218
|
+
if (cached)
|
|
219
|
+
return cached;
|
|
220
|
+
const pending = factory();
|
|
221
|
+
this.entries.set(key, pending);
|
|
222
|
+
pending.then(() => undefined, () => {
|
|
223
|
+
if (this.entries.get(key) === pending)
|
|
224
|
+
this.entries.delete(key);
|
|
225
|
+
});
|
|
226
|
+
return pending;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Compiles the editable React Island Host lifecycle into a browser ESM string.
|
|
231
|
+
*
|
|
232
|
+
* @remarks
|
|
233
|
+
* Compilation is cached by the complete entry configuration. Rejected promises
|
|
234
|
+
* are removed so a transient filesystem or bundler error can recover.
|
|
235
|
+
*/
|
|
236
|
+
export class IslandHydrationScriptCompiler {
|
|
237
|
+
compilationCache = new CompilationCache();
|
|
238
|
+
/**
|
|
239
|
+
* Compiles and caches one readable or minified Island Host entry.
|
|
240
|
+
*
|
|
241
|
+
* @param options - Complete entry imports, selector, identity, and output mode.
|
|
242
|
+
* @returns A browser ESM source string.
|
|
243
|
+
*/
|
|
244
|
+
compile(options) {
|
|
245
|
+
const key = getCacheKey(options);
|
|
246
|
+
return this.compilationCache.getOrCompile(key, () => compileIsland(options));
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Compiles editable Page lifecycle modules into browser ESM strings.
|
|
251
|
+
*
|
|
252
|
+
* @remarks
|
|
253
|
+
* The cache belongs to the service instance, allowing development restarts to
|
|
254
|
+
* discard framework-source changes without sharing stale output globally.
|
|
255
|
+
*/
|
|
256
|
+
export class PageHydrationScriptCompiler {
|
|
257
|
+
compilationCache = new CompilationCache();
|
|
258
|
+
/**
|
|
259
|
+
* Compiles and caches one readable or minified Page entry.
|
|
260
|
+
*
|
|
261
|
+
* @param options - Complete page imports, router contract, and output mode.
|
|
262
|
+
* @returns A browser ESM source string.
|
|
263
|
+
*/
|
|
264
|
+
compile(options) {
|
|
265
|
+
const key = getCacheKey(options);
|
|
266
|
+
return this.compilationCache.getOrCompile(key, () => compilePage(options));
|
|
267
|
+
}
|
|
268
|
+
}
|
|
@@ -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 {
|
|
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
|
-
}
|
|
@@ -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,112 +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
|
-
/**
|
|
36
|
-
* When true, the Page module exports a named `preload` and the generated
|
|
37
|
-
* entry must import, await, and re-export it.
|
|
38
|
-
*/
|
|
39
|
-
hasPagePreload?: boolean;
|
|
40
|
-
/** Optional router adapter for SPA navigation */
|
|
41
|
-
router?: ReactRouterAdapter;
|
|
42
|
-
/**
|
|
43
|
-
* Import path for shared layout composition helper.
|
|
44
|
-
*
|
|
45
|
-
* @remarks
|
|
46
|
-
* Required so callers (not this generator) decide vendor URL vs bare package.
|
|
47
|
-
*/
|
|
48
|
-
layoutComposeImportPath: string;
|
|
49
|
-
/**
|
|
50
|
-
* Import path for MDX page layout normalization helper.
|
|
51
|
-
*
|
|
52
|
-
* @remarks
|
|
53
|
-
* Required so callers (not this generator) decide vendor URL vs bare package.
|
|
54
|
-
*/
|
|
55
|
-
pageLayoutNormalizationImportPath: string;
|
|
56
|
-
/**
|
|
57
|
-
* Optional import path for the page-data reader.
|
|
58
|
-
*
|
|
59
|
-
* @remarks
|
|
60
|
-
* When omitted, hydration scripts inline the reader so native browser ESM /
|
|
61
|
-
* HMR entry evaluation does not depend on bare `@ecopages/react/*` imports.
|
|
62
|
-
* Browser unit tests that execute `data:` scripts may still pass a resolvable URL.
|
|
63
|
-
*/
|
|
64
|
-
pageDataReaderImportPath?: string;
|
|
65
|
-
};
|
|
66
|
-
export type IslandHydrationScriptOptions = {
|
|
67
|
-
/** Bundled browser module path for the island component. */
|
|
68
|
-
importPath: string;
|
|
69
|
-
/** Stable id of the island bootstrap script tag in the document. */
|
|
70
|
-
scriptId: string;
|
|
71
|
-
/** Browser import path for React runtime. */
|
|
72
|
-
reactImportPath: string;
|
|
73
|
-
/** Browser import path for react-dom/client runtime. */
|
|
74
|
-
reactDomClientImportPath: string;
|
|
75
|
-
/** Selector that resolves to all SSR root elements for this island component. */
|
|
76
|
-
targetSelector: string;
|
|
77
|
-
/** Optional stable component id used to resolve named exports reliably. */
|
|
78
|
-
componentRef?: string;
|
|
79
|
-
/** Optional source file hint used as fallback for component resolution. */
|
|
80
|
-
componentFile?: string;
|
|
81
|
-
/**
|
|
82
|
-
* When true, emit a compact source string.
|
|
83
|
-
*
|
|
84
|
-
* @remarks
|
|
85
|
-
* Island bootstraps use `bundle: false`, so compact output must be generated
|
|
86
|
-
* here rather than delegated to the bundler.
|
|
87
|
-
*/
|
|
88
|
-
minify: boolean;
|
|
89
|
-
/**
|
|
90
|
-
* When true, register an HMR handler that hot-imports the dev transform module.
|
|
91
|
-
*/
|
|
92
|
-
hmrEnabled?: boolean;
|
|
93
|
-
};
|
|
94
|
-
/**
|
|
95
|
-
* Creates a page hydration entry module.
|
|
96
|
-
*
|
|
97
|
-
* @remarks
|
|
98
|
-
* Always emits readable source. Production page assets set `bundle: true` so
|
|
99
|
-
* core's content-script processor minifies the result. Do not hand-minify here.
|
|
100
|
-
* If the Page exports `preload`, the generated entry imports, awaits, and
|
|
101
|
-
* re-exports it. Pages without that export keep a default import so the
|
|
102
|
-
* bundler does not warn about a missing named export.
|
|
103
|
-
*/
|
|
104
|
-
export declare function createHydrationScript(options: HydrationScriptOptions): string;
|
|
105
|
-
/**
|
|
106
|
-
* Creates the client bootstrap for component-level React islands.
|
|
107
|
-
*
|
|
108
|
-
* @remarks
|
|
109
|
-
* Island scripts use `bundle: false`, so compact output still needs a
|
|
110
|
-
* handwritten string.
|
|
111
|
-
*/
|
|
112
|
-
export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;
|