@ecopages/react 0.2.0-rc.5 → 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
package/README.md
CHANGED
|
@@ -31,7 +31,7 @@ For component-level islands, Ecopages React uses this contract:
|
|
|
31
31
|
|
|
32
32
|
- SSR output preserves the authored DOM structure (no unnecessary wrapper elements).
|
|
33
33
|
- A stable island host contract is stamped on the component SSR root via core (`data-eco-island`, `data-eco-island-integration`, `data-eco-component-id`, optional `data-eco-component-key` / `data-eco-props`).
|
|
34
|
-
- The island runtime
|
|
34
|
+
- The island runtime keeps the SSR host and its children in place and hydrates that host with `hydrateRoot()`. The host uses `display: contents` so it does not introduce an extra layout box. Full-page hydration paths also use `hydrateRoot()`.
|
|
35
35
|
|
|
36
36
|
> [!TIP]
|
|
37
37
|
> **Full React SPA Routing:**
|
|
@@ -75,6 +75,7 @@ Important:
|
|
|
75
75
|
|
|
76
76
|
- Components that may render foreign children must declare those children in `config.dependencies.components`.
|
|
77
77
|
- Ecopages validates mixed-renderer ownership from declared dependencies during render preparation. It does not infer every foreign subtree from rendered HTML alone.
|
|
78
|
+
- Route-level dependency resolvers can supply Components at request time; React includes those resolved roots when deciding whether a Foreign Subtree needs handoff.
|
|
78
79
|
- React still keeps its own child transport and hydration rules for React-owned subtrees.
|
|
79
80
|
|
|
80
81
|
## Server and Client Graph Contract
|
|
@@ -203,7 +204,7 @@ Hydration must rebuild the same tree the server rendered.
|
|
|
203
204
|
|
|
204
205
|
That applies to both:
|
|
205
206
|
|
|
206
|
-
-
|
|
207
|
+
- page hydration lifecycle in [src/hydration/browser/page-hydration.ts](src/hydration/browser/page-hydration.ts)
|
|
207
208
|
- router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
|
|
208
209
|
|
|
209
210
|
If the page render receives `locals` on the server and the layout also depends on those values, the client must pass the same serialized `locals` into the layout during hydration. Otherwise React will detect a mismatch.
|
|
@@ -214,7 +215,7 @@ The main regression coverage lives in:
|
|
|
214
215
|
|
|
215
216
|
- [src/client-graph/boundary-plugin.test.ts](src/client-graph/boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
|
|
216
217
|
- [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
|
|
217
|
-
- [src/hydration/hydration-
|
|
218
|
+
- [src/hydration/hydration-script-compiler.test.ts](src/hydration/hydration-script-compiler.test.ts): verifies editable browser sources compile to readable and minified entries.
|
|
218
219
|
- [../../react-router/test/hmr-reload.test.browser.ts](../../react-router/test/hmr-reload.test.browser.ts): verifies router-backed layout hydration receives `locals` with `persistLayouts` both enabled and disabled.
|
|
219
220
|
|
|
220
221
|
If you change the AST transform or hydration flow, update the corresponding tests in the same change.
|
|
@@ -243,7 +244,23 @@ The fix is **shared browser runtime vendors**: selected npm packages are built o
|
|
|
243
244
|
|
|
244
245
|
In `ecopages dev`, page modules are served from `/assets/__eco_dev__/` and should import `/assets/vendors/*` for shared packages instead of inlining `node_modules`. Kitchen-sink routes `/vendor-share/a` and `/vendor-share/b` (with `runtimeModules: ['zod']`) are the reference fixture; see `playground/kitchen-sink/e2e/shared-vendors.test.e2e.ts`.
|
|
245
246
|
|
|
246
|
-
The Ecopages dev toolbar **Islands** app inspects `data-eco-island`, `data-eco-component-id`, `data-eco-props`, and `window.__ECO_PAGES__.islandRoots` during development.
|
|
247
|
+
The Ecopages dev toolbar **Islands** app inspects `data-eco-island`, `data-eco-component-id`, `data-eco-props`, and `window.__ECO_PAGES__.islandRoots` during development. React component islands are emitted as `<eco-island style="display:contents">` hosts during SSR and hydrated in place; the client adds `data-eco-hydrated` after the initial commit. `display: contents` keeps the host from introducing a layout box while preserving it as the hydration and diagnostics boundary.
|
|
248
|
+
|
|
249
|
+
The browser lifecycle is maintained as typed code in `src/hydration/browser/`.
|
|
250
|
+
Production island bootstraps are generated from that source by the server-side
|
|
251
|
+
Rolldown compiler in `src/hydration/hydration-script-compiler.ts`, which keeps
|
|
252
|
+
React, ReactDOM, and the component entry as external browser imports. This keeps
|
|
253
|
+
the generated script compact without requiring a second handwritten minified
|
|
254
|
+
implementation.
|
|
255
|
+
|
|
256
|
+
Page HMR registers before initial preload, but publishes a replacement component
|
|
257
|
+
only after its preload succeeds. Each handler belongs to the page generation in
|
|
258
|
+
which it was registered. Navigation cleanup invalidates both pending updates and
|
|
259
|
+
later calls to retained handlers, preventing updates to a replacement page root.
|
|
260
|
+
|
|
261
|
+
Hydration preserves the SSR DOM when the server and client trees match. A
|
|
262
|
+
component that renders different markup in the browser can still produce a
|
|
263
|
+
normal React hydration mismatch or layout shift.
|
|
247
264
|
|
|
248
265
|
Auto-discovery removes the need to hand-maintain `runtimeModules` for the common case — a query-client layout that imports `@tanstack/react-query` is enough when discovery is configured correctly.
|
|
249
266
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ecopages/react",
|
|
3
|
-
"version": "0.2.0-rc.
|
|
3
|
+
"version": "0.2.0-rc.7",
|
|
4
4
|
"description": "React integration for Ecopages",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ecopages",
|
|
@@ -104,19 +104,20 @@
|
|
|
104
104
|
"directory": "packages/integrations/react"
|
|
105
105
|
},
|
|
106
106
|
"peerDependencies": {
|
|
107
|
-
"@ecopages/core": "0.2.0-rc.
|
|
107
|
+
"@ecopages/core": "0.2.0-rc.7",
|
|
108
108
|
"@types/react": "^19",
|
|
109
109
|
"@types/react-dom": "^19",
|
|
110
110
|
"react": "^19",
|
|
111
111
|
"react-dom": "^19"
|
|
112
112
|
},
|
|
113
113
|
"dependencies": {
|
|
114
|
-
"@ecopages/file-system": "0.2.0-rc.
|
|
114
|
+
"@ecopages/file-system": "0.2.0-rc.7",
|
|
115
115
|
"@ecopages/logger": "^0.2.3",
|
|
116
|
-
"@ecopages/mdx": "0.2.0-rc.
|
|
116
|
+
"@ecopages/mdx": "0.2.0-rc.7",
|
|
117
117
|
"@mdx-js/mdx": "^3.1.1",
|
|
118
118
|
"oxc-parser": "^0.141.0",
|
|
119
119
|
"oxc-transform": "^0.141.0",
|
|
120
|
+
"rolldown": "^1.1.0",
|
|
120
121
|
"source-map": "^0.8.0",
|
|
121
122
|
"vfile": "^6.0.3"
|
|
122
123
|
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser-side React Island Host lifecycle.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* This module intentionally receives React's browser runtime as a value. The
|
|
6
|
+
* server entry compiler can therefore keep the application's React and
|
|
7
|
+
* ReactDOM imports external while bundling this framework-owned lifecycle.
|
|
8
|
+
*/
|
|
9
|
+
export type IslandComponent = (props: Record<string, unknown>) => unknown;
|
|
10
|
+
export type IslandReactRuntime = {
|
|
11
|
+
hydrateRoot: (target: HTMLElement, tree: unknown, options?: {
|
|
12
|
+
onRecoverableError?: (error: unknown) => void;
|
|
13
|
+
}) => IslandRoot;
|
|
14
|
+
createElement: (type: unknown, props: Record<string, unknown>) => unknown;
|
|
15
|
+
useEffect: (effect: () => void, dependencies: unknown[]) => void;
|
|
16
|
+
};
|
|
17
|
+
export type IslandRoot = {
|
|
18
|
+
render: (tree: unknown) => void;
|
|
19
|
+
unmount: () => void;
|
|
20
|
+
};
|
|
21
|
+
/** Shared browser state for all Island Host entries on one document. */
|
|
22
|
+
export type IslandHydrationRuntime = {
|
|
23
|
+
islandRoots: Record<string, IslandRoot>;
|
|
24
|
+
islandComponents: Record<string, IslandComponent>;
|
|
25
|
+
observer?: MutationObserver;
|
|
26
|
+
};
|
|
27
|
+
/** Configuration for one compiled React Island Host entry. */
|
|
28
|
+
export type IslandHydrationOptions = {
|
|
29
|
+
targetSelector: string;
|
|
30
|
+
componentModule: Record<string, unknown>;
|
|
31
|
+
componentRef?: string;
|
|
32
|
+
componentFile?: string;
|
|
33
|
+
scriptId: string;
|
|
34
|
+
runtime: IslandReactRuntime;
|
|
35
|
+
runtimeState: IslandHydrationRuntime;
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* Returns the shared page runtime used by all React Island Host entries.
|
|
39
|
+
*
|
|
40
|
+
* @remarks
|
|
41
|
+
* Keeping initialization here means generated entries only describe their
|
|
42
|
+
* component and selector; they do not duplicate global runtime setup.
|
|
43
|
+
*
|
|
44
|
+
* @returns The shared mutable state used by all island entries on this page.
|
|
45
|
+
*/
|
|
46
|
+
export declare function getIslandHydrationRuntime(): IslandHydrationRuntime;
|
|
47
|
+
/**
|
|
48
|
+
* Registers the development HMR callback for one component module.
|
|
49
|
+
*
|
|
50
|
+
* @remarks
|
|
51
|
+
* The callback imports the replacement module and delegates to
|
|
52
|
+
* {@link updateIslands}, which updates every live host matching this entry.
|
|
53
|
+
* The dynamic import function is supplied by the generated entry so HMR keeps
|
|
54
|
+
* the browser's normal module-resolution behavior.
|
|
55
|
+
*
|
|
56
|
+
* @param options - Entry configuration whose hosts should receive updates.
|
|
57
|
+
* @param importModule - Browser dynamic-import function for the replacement module.
|
|
58
|
+
* @param importPath - HMR source URL used as the global handler key.
|
|
59
|
+
*/
|
|
60
|
+
export declare function registerIslandHmr(options: IslandHydrationOptions, importModule: (url: string) => Promise<Record<string, unknown>>, importPath?: string): void;
|
|
61
|
+
/**
|
|
62
|
+
* Hydrates every eligible host for one component entry.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Existing host records are skipped. This makes rerun scripts idempotent and
|
|
66
|
+
* avoids calling `render` while an initial `hydrateRoot` commit is
|
|
67
|
+
* still pending.
|
|
68
|
+
*
|
|
69
|
+
* @param options - Component, selector, React runtime, and shared state for the entry.
|
|
70
|
+
*/
|
|
71
|
+
export declare function mountIslands(options: IslandHydrationOptions): void;
|
|
72
|
+
/**
|
|
73
|
+
* Applies a hot-reloaded component to every live host owned by this entry.
|
|
74
|
+
*
|
|
75
|
+
* @remarks
|
|
76
|
+
* Updates arriving before the initial commit are stored on each host and
|
|
77
|
+
* rendered by {@link IslandLifecycle} after it marks that host hydrated.
|
|
78
|
+
*
|
|
79
|
+
* @param options - The live entry configuration and runtime state.
|
|
80
|
+
* @param newModule - Newly imported component module.
|
|
81
|
+
*/
|
|
82
|
+
export declare function updateIslands(options: IslandHydrationOptions, newModule: Record<string, unknown>): void;
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser-side React Island Host lifecycle.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* This module intentionally receives React's browser runtime as a value. The
|
|
6
|
+
* server entry compiler can therefore keep the application's React and
|
|
7
|
+
* ReactDOM imports external while bundling this framework-owned lifecycle.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Returns the shared page runtime used by all React Island Host entries.
|
|
11
|
+
*
|
|
12
|
+
* @remarks
|
|
13
|
+
* Keeping initialization here means generated entries only describe their
|
|
14
|
+
* component and selector; they do not duplicate global runtime setup.
|
|
15
|
+
*
|
|
16
|
+
* @returns The shared mutable state used by all island entries on this page.
|
|
17
|
+
*/
|
|
18
|
+
export function getIslandHydrationRuntime() {
|
|
19
|
+
const pageWindow = window;
|
|
20
|
+
const pageRuntime = (pageWindow.__ECO_PAGES__ ??= {});
|
|
21
|
+
pageRuntime.islandRoots ??= {};
|
|
22
|
+
pageRuntime.islandComponents ??= {};
|
|
23
|
+
pageRuntime.__ecoIslandRuntime ??= {
|
|
24
|
+
islandRoots: pageRuntime.islandRoots,
|
|
25
|
+
islandComponents: pageRuntime.islandComponents,
|
|
26
|
+
};
|
|
27
|
+
pageRuntime.__ecoIslandRuntime.islandRoots = pageRuntime.islandRoots;
|
|
28
|
+
pageRuntime.__ecoIslandRuntime.islandComponents = pageRuntime.islandComponents;
|
|
29
|
+
return pageRuntime.__ecoIslandRuntime;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Registers the development HMR callback for one component module.
|
|
33
|
+
*
|
|
34
|
+
* @remarks
|
|
35
|
+
* The callback imports the replacement module and delegates to
|
|
36
|
+
* {@link updateIslands}, which updates every live host matching this entry.
|
|
37
|
+
* The dynamic import function is supplied by the generated entry so HMR keeps
|
|
38
|
+
* the browser's normal module-resolution behavior.
|
|
39
|
+
*
|
|
40
|
+
* @param options - Entry configuration whose hosts should receive updates.
|
|
41
|
+
* @param importModule - Browser dynamic-import function for the replacement module.
|
|
42
|
+
* @param importPath - HMR source URL used as the global handler key.
|
|
43
|
+
*/
|
|
44
|
+
export function registerIslandHmr(options, importModule, importPath) {
|
|
45
|
+
if (!importPath)
|
|
46
|
+
return;
|
|
47
|
+
const pageWindow = window;
|
|
48
|
+
const pageRuntime = (pageWindow.__ECO_PAGES__ ??= {});
|
|
49
|
+
pageRuntime.hmrHandlers ??= {};
|
|
50
|
+
pageRuntime.hmrHandlers[importPath] = async (url) => {
|
|
51
|
+
updateIslands(options, await importModule(url));
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Selects the component exported by a browser entry for the current Island Host.
|
|
56
|
+
*
|
|
57
|
+
* @remarks
|
|
58
|
+
* Component identity is preferred when a file exports several components. The
|
|
59
|
+
* default export and then the first function remain compatibility fallbacks for
|
|
60
|
+
* entries without framework identity metadata.
|
|
61
|
+
*/
|
|
62
|
+
function resolveComponent(module, componentRef, componentFile) {
|
|
63
|
+
const values = Object.values(module).filter((entry) => typeof entry === 'function');
|
|
64
|
+
if (componentRef) {
|
|
65
|
+
const matchById = values.find((entry) => entry.config?.identity?.id === componentRef);
|
|
66
|
+
if (matchById)
|
|
67
|
+
return matchById;
|
|
68
|
+
}
|
|
69
|
+
if (componentFile) {
|
|
70
|
+
const matchByFile = values.find((entry) => entry.config?.identity?.file === componentFile);
|
|
71
|
+
if (matchByFile)
|
|
72
|
+
return matchByFile;
|
|
73
|
+
}
|
|
74
|
+
if (typeof module.default === 'function')
|
|
75
|
+
return module.default;
|
|
76
|
+
return values[0] ?? null;
|
|
77
|
+
}
|
|
78
|
+
function getComponentId(target) {
|
|
79
|
+
return target.getAttribute('data-eco-component-id');
|
|
80
|
+
}
|
|
81
|
+
function getIslandIdentity(target) {
|
|
82
|
+
return getComponentId(target) ?? target.getAttribute('data-eco-component-key') ?? 'unknown';
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Adds the initial-commit marker while keeping one stable React component type
|
|
86
|
+
* around the application component. A stable type lets HMR update props without
|
|
87
|
+
* remounting this lifecycle boundary on every render.
|
|
88
|
+
*/
|
|
89
|
+
function IslandLifecycle({ target, runtime, Component, props }) {
|
|
90
|
+
runtime.useEffect(() => {
|
|
91
|
+
target.setAttribute('data-eco-hydrated', 'true');
|
|
92
|
+
const record = target.__eco_island;
|
|
93
|
+
if (!record)
|
|
94
|
+
return;
|
|
95
|
+
record.hydrated = true;
|
|
96
|
+
if (record.pendingComponent) {
|
|
97
|
+
const pendingComponent = record.pendingComponent;
|
|
98
|
+
record.pendingComponent = undefined;
|
|
99
|
+
record.root.render(runtime.createElement(IslandLifecycle, {
|
|
100
|
+
target,
|
|
101
|
+
runtime,
|
|
102
|
+
Component: pendingComponent,
|
|
103
|
+
props: readProps(target),
|
|
104
|
+
}));
|
|
105
|
+
}
|
|
106
|
+
}, [target, runtime]);
|
|
107
|
+
return runtime.createElement(Component, props);
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Decodes the serialized props stamped on an Island Host by the server.
|
|
111
|
+
* Malformed or non-object payloads become an empty props object so a broken
|
|
112
|
+
* diagnostic attribute cannot prevent the rest of the page from hydrating.
|
|
113
|
+
*/
|
|
114
|
+
function readProps(target) {
|
|
115
|
+
try {
|
|
116
|
+
const encoded = target.getAttribute('data-eco-props') ?? 'e30=';
|
|
117
|
+
const parsed = JSON.parse(atob(encoded));
|
|
118
|
+
return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
|
|
119
|
+
? parsed
|
|
120
|
+
: {};
|
|
121
|
+
}
|
|
122
|
+
catch {
|
|
123
|
+
return {};
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* Unmounts a disconnected island and removes only its matching registry entry.
|
|
128
|
+
*
|
|
129
|
+
* @remarks
|
|
130
|
+
* Connectivity is checked by the observer callback, after the mutation batch,
|
|
131
|
+
* so moving a host within the document does not release its React root.
|
|
132
|
+
*/
|
|
133
|
+
function releaseIsland(target, runtimeState) {
|
|
134
|
+
if (target.isConnected)
|
|
135
|
+
return;
|
|
136
|
+
const record = target.__eco_island;
|
|
137
|
+
if (!record)
|
|
138
|
+
return;
|
|
139
|
+
record.root.unmount();
|
|
140
|
+
const componentId = getComponentId(target);
|
|
141
|
+
if (componentId && runtimeState.islandRoots[componentId] === record.root) {
|
|
142
|
+
delete runtimeState.islandRoots[componentId];
|
|
143
|
+
}
|
|
144
|
+
delete target.__eco_island;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Installs the one document observer shared by all island entries on the page.
|
|
148
|
+
* The observer releases roots for removed hosts and their descendants.
|
|
149
|
+
*/
|
|
150
|
+
function ensureObserver(runtimeState) {
|
|
151
|
+
if (runtimeState.observer || !document.documentElement)
|
|
152
|
+
return;
|
|
153
|
+
runtimeState.observer = new MutationObserver((mutations) => {
|
|
154
|
+
for (const mutation of mutations) {
|
|
155
|
+
for (const node of mutation.removedNodes) {
|
|
156
|
+
if (!(node instanceof HTMLElement))
|
|
157
|
+
continue;
|
|
158
|
+
releaseIsland(node, runtimeState);
|
|
159
|
+
for (const target of node.querySelectorAll('[data-eco-island]'))
|
|
160
|
+
releaseIsland(target, runtimeState);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
});
|
|
164
|
+
runtimeState.observer.observe(document.documentElement, { childList: true, subtree: true });
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Hydrates one server-emitted Island Host in place and records its lifecycle.
|
|
168
|
+
*
|
|
169
|
+
* @remarks
|
|
170
|
+
* The record is attached immediately after `hydrateRoot` returns so
|
|
171
|
+
* duplicate startup and HMR can see the host before React's initial effect runs.
|
|
172
|
+
*/
|
|
173
|
+
function hydrateTarget(target, component, runtime, runtimeState) {
|
|
174
|
+
const root = runtime.hydrateRoot(target, runtime.createElement(IslandLifecycle, { target, runtime, Component: component, props: readProps(target) }), {
|
|
175
|
+
onRecoverableError: (error) => console.warn('[ecopages] Island hydration error', getIslandIdentity(target), error),
|
|
176
|
+
});
|
|
177
|
+
const record = { root, hydrated: false, component };
|
|
178
|
+
target.__eco_island = record;
|
|
179
|
+
const componentId = getComponentId(target);
|
|
180
|
+
if (componentId)
|
|
181
|
+
runtimeState.islandRoots[componentId] = record.root;
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Hydrates every eligible host for one component entry.
|
|
185
|
+
*
|
|
186
|
+
* @remarks
|
|
187
|
+
* Existing host records are skipped. This makes rerun scripts idempotent and
|
|
188
|
+
* avoids calling `render` while an initial `hydrateRoot` commit is
|
|
189
|
+
* still pending.
|
|
190
|
+
*
|
|
191
|
+
* @param options - Component, selector, React runtime, and shared state for the entry.
|
|
192
|
+
*/
|
|
193
|
+
export function mountIslands(options) {
|
|
194
|
+
const resolvedComponent = resolveComponent(options.componentModule, options.componentRef ?? '', options.componentFile ?? '');
|
|
195
|
+
ensureObserver(options.runtimeState);
|
|
196
|
+
const pageRuntime = (window.__ECO_PAGES__ ??= {});
|
|
197
|
+
pageRuntime.rerunScripts ??= {};
|
|
198
|
+
pageRuntime.rerunScripts[options.scriptId] = () => mountIslands(options);
|
|
199
|
+
const scriptId = options.scriptId;
|
|
200
|
+
const component = options.runtimeState.islandComponents[scriptId] ?? resolvedComponent;
|
|
201
|
+
if (!component)
|
|
202
|
+
return;
|
|
203
|
+
options.runtimeState.islandComponents[scriptId] = component;
|
|
204
|
+
for (const element of document.querySelectorAll(options.targetSelector)) {
|
|
205
|
+
const target = element;
|
|
206
|
+
if (target.__eco_island?.root)
|
|
207
|
+
continue;
|
|
208
|
+
hydrateTarget(target, component, options.runtime, options.runtimeState);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* Applies a hot-reloaded component to every live host owned by this entry.
|
|
213
|
+
*
|
|
214
|
+
* @remarks
|
|
215
|
+
* Updates arriving before the initial commit are stored on each host and
|
|
216
|
+
* rendered by {@link IslandLifecycle} after it marks that host hydrated.
|
|
217
|
+
*
|
|
218
|
+
* @param options - The live entry configuration and runtime state.
|
|
219
|
+
* @param newModule - Newly imported component module.
|
|
220
|
+
*/
|
|
221
|
+
export function updateIslands(options, newModule) {
|
|
222
|
+
const component = resolveComponent(newModule, options.componentRef ?? '', options.componentFile ?? '');
|
|
223
|
+
if (!component)
|
|
224
|
+
return;
|
|
225
|
+
options.componentModule = newModule;
|
|
226
|
+
const scriptId = options.scriptId;
|
|
227
|
+
options.runtimeState.islandComponents[scriptId] = component;
|
|
228
|
+
for (const element of document.querySelectorAll(options.targetSelector)) {
|
|
229
|
+
const target = element;
|
|
230
|
+
const record = target.__eco_island;
|
|
231
|
+
if (!record) {
|
|
232
|
+
hydrateTarget(target, component, options.runtime, options.runtimeState);
|
|
233
|
+
continue;
|
|
234
|
+
}
|
|
235
|
+
record.component = component;
|
|
236
|
+
if (!record.hydrated) {
|
|
237
|
+
record.pendingComponent = component;
|
|
238
|
+
continue;
|
|
239
|
+
}
|
|
240
|
+
record.root.render(options.runtime.createElement(IslandLifecycle, {
|
|
241
|
+
target,
|
|
242
|
+
runtime: options.runtime,
|
|
243
|
+
Component: component,
|
|
244
|
+
props: readProps(target),
|
|
245
|
+
}));
|
|
246
|
+
}
|
|
247
|
+
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser-side React page lifecycle.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* The entry module supplies the page tree and module resolution details. This
|
|
6
|
+
* module owns document state, navigation ownership, cleanup, and HMR so those
|
|
7
|
+
* behaviors stay identical for readable and compiled bootstraps.
|
|
8
|
+
*/
|
|
9
|
+
export type PageRoot = {
|
|
10
|
+
render: (tree: unknown) => void;
|
|
11
|
+
unmount: () => void;
|
|
12
|
+
};
|
|
13
|
+
export type PageReactRuntime = {
|
|
14
|
+
hydrateRoot: (target: HTMLElement, tree: unknown, options?: {
|
|
15
|
+
onRecoverableError?: (error: unknown) => void;
|
|
16
|
+
}) => PageRoot;
|
|
17
|
+
createElement: (...args: unknown[]) => unknown;
|
|
18
|
+
};
|
|
19
|
+
export type PageData = {
|
|
20
|
+
moduleUrl?: string;
|
|
21
|
+
props: Record<string, unknown>;
|
|
22
|
+
};
|
|
23
|
+
export type PageModule = {
|
|
24
|
+
Page: unknown;
|
|
25
|
+
preload?: (props: Record<string, unknown>) => void | Promise<void>;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Normalizes a loaded Page module into the shape used by hydration and HMR.
|
|
29
|
+
*
|
|
30
|
+
* @remarks
|
|
31
|
+
* MDX modules carry page configuration as a named export and need layout
|
|
32
|
+
* normalization before React reconstructs the page tree. Plain React modules
|
|
33
|
+
* use their default export while still allowing a named `preload`.
|
|
34
|
+
*
|
|
35
|
+
* @param module - Imported Page or MDX module namespace.
|
|
36
|
+
* @param isMdx - Whether the module carries MDX page configuration.
|
|
37
|
+
* @param normalizePageConfig - Integration helper for normalizing MDX layouts.
|
|
38
|
+
* @returns The Page component and optional preload hook used by hydration/HMR.
|
|
39
|
+
*/
|
|
40
|
+
export declare function resolvePageModule(module: Record<string, unknown>, isMdx: boolean, normalizePageConfig?: (config: unknown) => void): PageModule;
|
|
41
|
+
/** Configuration passed from a generated Page hydration entry. */
|
|
42
|
+
export type PageHydrationOptions = {
|
|
43
|
+
scriptId: string;
|
|
44
|
+
pageModuleUrl: string;
|
|
45
|
+
Page: unknown;
|
|
46
|
+
pageDataReader: {
|
|
47
|
+
readPageDataDocument: () => PageData;
|
|
48
|
+
getPageDataFromDocument: () => Record<string, unknown>;
|
|
49
|
+
};
|
|
50
|
+
runtime: PageReactRuntime;
|
|
51
|
+
createTree: (Page: unknown, props: Record<string, unknown>) => unknown;
|
|
52
|
+
hasRouter: boolean;
|
|
53
|
+
isMdx: boolean;
|
|
54
|
+
normalizePageConfig?: (config: unknown) => void;
|
|
55
|
+
hmr?: {
|
|
56
|
+
importPath: string;
|
|
57
|
+
getLayoutStack?: (Page: unknown) => string;
|
|
58
|
+
};
|
|
59
|
+
preload?: (props: Record<string, unknown>) => void | Promise<void>;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* Registers and starts the Page lifecycle when its persistent script is present.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Restores lifecycle registration, router ownership, and HMR generation binding
|
|
66
|
+
* whenever the page is activated or rerun after navigation.
|
|
67
|
+
*
|
|
68
|
+
* @param options - Generated entry configuration for the current Page.
|
|
69
|
+
*/
|
|
70
|
+
export declare function startPageHydration(options: PageHydrationOptions): void;
|