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

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 (109) hide show
  1. package/README.md +168 -6
  2. package/package.json +51 -26
  3. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  4. package/src/bundling/bootstrap-package-paths.js +6 -0
  5. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +21 -8
  6. package/src/{services/react-bundle.service.js → bundling/bundle.js} +53 -21
  7. package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
  8. package/src/bundling/discover-layout-runtime-modules.js +180 -0
  9. package/src/bundling/runtime-alias-map.d.ts +10 -0
  10. package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +13 -2
  11. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +30 -5
  12. package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +104 -8
  13. package/src/bundling/runtime-mode.d.ts +9 -0
  14. package/src/bundling/runtime-mode.js +6 -0
  15. package/src/bundling/runtime-modules.d.ts +29 -0
  16. package/src/bundling/runtime-modules.js +38 -0
  17. package/src/client-graph/ast-transform.d.ts +18 -0
  18. package/src/{utils/client-graph-boundary-plugin.js → client-graph/ast-transform.js} +15 -232
  19. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
  20. package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
  21. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
  22. package/src/client-graph/boundary-plugin.js +107 -0
  23. package/src/{utils → client-graph}/component-config-traversal.js +4 -2
  24. package/src/{utils → client-graph}/reachability-analyzer.d.ts +2 -2
  25. package/src/{utils → client-graph}/reachability-analyzer.js +4 -1
  26. package/src/client-graph/specifier-classification.d.ts +75 -0
  27. package/src/client-graph/specifier-classification.js +155 -0
  28. package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +19 -6
  29. package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +154 -133
  30. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  31. package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
  32. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  33. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  34. package/src/hydration/bootstrap-imports.d.ts +25 -0
  35. package/src/hydration/bootstrap-imports.js +23 -0
  36. package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
  37. package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +63 -56
  38. package/src/hydration/hydration-scripts.d.ts +100 -0
  39. package/src/hydration/hydration-scripts.js +350 -0
  40. package/src/{utils → hydration}/hydration-scripts.test.browser.js +11 -5
  41. package/src/hydration/page-data-manifest.d.ts +58 -0
  42. package/src/hydration/page-data-manifest.js +53 -0
  43. package/src/hydration/page-data-reader.d.ts +31 -0
  44. package/src/hydration/page-data-reader.js +64 -0
  45. package/src/hydration/page-payload.d.ts +67 -0
  46. package/src/hydration/page-payload.js +104 -0
  47. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  48. package/src/hydration/serialize-page-data-script.js +31 -0
  49. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
  50. package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +8 -10
  51. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  52. package/src/mdx/mdx-loader-plugin.js +11 -0
  53. package/src/page/page-module.d.ts +46 -0
  54. package/src/page/page-module.js +72 -0
  55. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +8 -3
  56. package/src/{react.plugin.js → plugin/react.plugin.js} +78 -54
  57. package/src/plugin/react.types.d.ts +149 -0
  58. package/src/render/component-ownership.d.ts +50 -0
  59. package/src/render/component-ownership.js +23 -0
  60. package/src/render/component-ssr.d.ts +113 -0
  61. package/src/render/component-ssr.js +202 -0
  62. package/src/render/errors.d.ts +16 -0
  63. package/src/render/errors.js +18 -0
  64. package/src/render/layout-compose.d.ts +66 -0
  65. package/src/render/layout-compose.js +106 -0
  66. package/src/render/react-renderer.d.ts +138 -0
  67. package/src/render/react-renderer.js +481 -0
  68. package/src/render/react-runtime.d.ts +13 -0
  69. package/src/render/react-runtime.js +21 -0
  70. package/src/render/unified-layout-composition.d.ts +53 -0
  71. package/src/render/unified-layout-composition.js +89 -0
  72. package/src/react-renderer.d.ts +0 -233
  73. package/src/react-renderer.js +0 -622
  74. package/src/react.types.d.ts +0 -88
  75. package/src/services/pages-index.d.ts +0 -64
  76. package/src/services/pages-index.js +0 -73
  77. package/src/services/react-page-module.service.d.ts +0 -88
  78. package/src/services/react-page-module.service.js +0 -166
  79. package/src/services/react-page-payload.service.d.ts +0 -46
  80. package/src/services/react-page-payload.service.js +0 -67
  81. package/src/utils/hydration-scripts.d.ts +0 -92
  82. package/src/utils/hydration-scripts.js +0 -358
  83. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  84. package/src/utils/react-mdx-loader-plugin.js +0 -45
  85. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  86. /package/src/{utils → app}/client-only.d.ts +0 -0
  87. /package/src/{utils → app}/client-only.js +0 -0
  88. /package/src/{utils → app}/dynamic.d.ts +0 -0
  89. /package/src/{utils → app}/dynamic.js +0 -0
  90. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  91. /package/src/{utils → app}/dynamic.test.browser.js +0 -0
  92. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  93. /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
  94. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  95. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  96. /package/src/{utils → client-graph}/declared-modules.js +0 -0
  97. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  98. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  99. /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
  100. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  101. /package/src/{utils → hmr}/hmr-scripts.js +0 -0
  102. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  103. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  104. /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
  105. /package/src/{react.types.js → plugin/react.types.js} +0 -0
  106. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  107. /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
  108. /package/src/{utils → render}/html-boundary.d.ts +0 -0
  109. /package/src/{utils → render}/html-boundary.js +0 -0
package/README.md CHANGED
@@ -109,6 +109,14 @@ Think about each React page as two related graphs:
109
109
 
110
110
  The React integration builds the client graph conservatively. If a server-only module becomes reachable from the hydrated render path, the build should fail rather than silently shipping unsafe code.
111
111
 
112
+ ### `explicitGraph` option
113
+
114
+ `reactPlugin({ explicitGraph: true })` forces the page browser graph (hydration assets) to emit for every React page, even when the page does not declare `dependencies.modules` and no router is configured.
115
+
116
+ It does **not** disable the client-graph AST boundary. Server-only `eco.page(...)` options such as `middleware` and `requires` are still stripped from browser bundles. With a router adapter, page hydration is already always on, so the option is redundant for SPA apps.
117
+
118
+ The option name is historical — it forces hydration asset emission, it does not mean “skip graph transforms.”
119
+
112
120
  ### What Stays and What Goes
113
121
 
114
122
  The client bundle keeps:
@@ -131,7 +139,7 @@ Important:
131
139
 
132
140
  ### AST Pipeline Order
133
141
 
134
- The browser-bound transform in [src/utils/client-graph-boundary-plugin.ts](src/utils/client-graph-boundary-plugin.ts) follows this order:
142
+ The browser-bound transform in [src/client-graph/boundary-plugin.ts](src/client-graph/boundary-plugin.ts) follows this order:
135
143
 
136
144
  1. Parse the module and build a reachability view of the client render graph.
137
145
  2. Remove imports that are not allowed or not reachable from the client graph.
@@ -166,7 +174,7 @@ The fix is to strip server-only `eco.page(...)` options after import pruning, wh
166
174
 
167
175
  The browser must not receive arbitrary request-scoped data.
168
176
 
169
- The React renderer in [src/react-renderer.ts](src/react-renderer.ts) serializes only the top-level `locals` keys explicitly declared by `Page.requires`. If a page does not declare `requires`, no `locals` are serialized for hydration.
177
+ The React renderer in [src/render/react-renderer.ts](src/render/react-renderer.ts) serializes only the top-level `locals` keys explicitly declared by `Page.requires`. If a page does not declare `requires`, no `locals` are serialized for hydration.
170
178
 
171
179
  Example:
172
180
 
@@ -191,7 +199,7 @@ Hydration must rebuild the same tree the server rendered.
191
199
 
192
200
  That applies to both:
193
201
 
194
- - non-router hydration scripts in [src/utils/hydration-scripts.ts](src/utils/hydration-scripts.ts)
202
+ - non-router hydration scripts in [src/hydration/hydration-scripts.ts](src/hydration/hydration-scripts.ts)
195
203
  - router-backed hydration in [../../react-router/src/router.ts](../../react-router/src/router.ts)
196
204
 
197
205
  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.
@@ -200,9 +208,163 @@ If the page render receives `locals` on the server and the layout also depends o
200
208
 
201
209
  The main regression coverage lives in:
202
210
 
203
- - [src/utils/client-graph-boundary-plugin.test.ts](src/utils/client-graph-boundary-plugin.test.ts): verifies server-only `eco.page(...)` options are stripped from browser bundles.
204
- - [src/react-renderer.locals.test.ts](src/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
205
- - [src/utils/hydration-scripts.test.ts](src/utils/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
211
+ - [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.
212
+ - [src/render/react-renderer.locals.test.ts](src/render/react-renderer.locals.test.ts): verifies only declared `requires` keys are serialized into hydration payloads.
213
+ - [src/hydration/hydration-scripts.test.ts](src/hydration/hydration-scripts.test.ts): verifies non-router hydration passes serialized `locals` into layouts.
206
214
  - [../../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.
207
215
 
208
216
  If you change the AST transform or hydration flow, update the corresponding tests in the same change.
217
+
218
+ ### Nested layouts and unified SSR
219
+
220
+ Pages may declare `layout` as a single component or an **outer → inner** array on `eco.page()`. On the server, React-managed layout stacks compose through `composeDocumentShell` + `composeLayoutPageTree` so provider context reaches nested pages during SSR. On the client, `@ecopages/react-router` `PageContent` uses the same `composeLayoutPageTree` helper unless `persistLayouts` is enabled (then each tier is cached independently).
221
+
222
+ During SSR, `ReactRenderer` passes the app-resolved React runtime into `composeLayoutPageTree` via `options.react` so layout trees are built with the same module instance as `renderToString`. App code should import hooks and context from `react` normally; keep a single React version in the app dependency graph (avoid duplicate `react` copies in monorepos).
223
+
224
+ Layout prop factories receive `LayoutPropsContext` (`params`, `query`, `locals`). Route-scoped `locals` are passed to layout tiers via document-shell props during SSR; serialized `pageProps.locals` follow `Page.requires` and are intended for the page component.
225
+
226
+ - [src/render/layout-compose.ts](src/render/layout-compose.ts): shared client/SSR tree builder.
227
+ - [src/test/react-ssr-hydration-parity.test.tsx](src/test/react-ssr-hydration-parity.test.tsx): nested tier order parity between SSR and `composeLayoutPageTree`.
228
+ - [src/test/react-ssr-unified.test.tsx](src/test/react-ssr-unified.test.tsx): provider context through nested SSR layouts.
229
+
230
+ ### Shared runtime vendors (SPA + persisted layouts)
231
+
232
+ #### Mental model
233
+
234
+ With `ecoRouter()`, Ecopages keeps outer layout tiers mounted across client navigation (`persistLayouts` defaults to `true`). Each page chunk still loads separately, but provider layouts stay alive in the DOM.
235
+
236
+ That creates a module identity problem: if TanStack Query (or any shared provider library) is bundled into every page chunk separately, each chunk gets its own copy of the library and its own React context. Navigation then breaks with errors such as `No QueryClient set`, even though the provider component is still mounted.
237
+
238
+ The fix is **shared browser runtime vendors**: selected npm packages are built once into `/assets/vendors/*.js` and every page chunk imports the same public URL. React, React DOM, the router bundle, and auto-discovered layout runtime packages all follow this path.
239
+
240
+ 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.
241
+
242
+ #### When auto-discovery runs
243
+
244
+ Auto-discovery runs at plugin setup when **both** are true:
245
+
246
+ - `router` is passed to `reactPlugin()`
247
+ - The app config exposes `absolutePaths.projectDir`, `layoutsDir`, and `componentsDir`
248
+
249
+ Without `router`, only explicit `runtimeModules` entries are vendored.
250
+
251
+ #### Discovery modes
252
+
253
+ | Mode | Trigger | Layout roots scanned | npm packages collected |
254
+ | ---------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
255
+ | **Runtime-provider** (recommended) | At least one layout sets `runtimeProvider: true` | Only flagged layouts | Every reachable npm package in that layout's `render` graph |
256
+ | **Provider-scoped fallback** | No layout sets `runtimeProvider: true` | All `eco.layout(` files under `layouts/` and `components/` | npm packages imported from provider/context modules only |
257
+
258
+ The fallback exists for backward compatibility. Ecopages logs a debug message when fallback mode is active. Prefer explicit `runtimeProvider: true` on provider root layouts (for example a query-client tier) and omit it from shell-only layouts.
259
+
260
+ #### What gets discovered
261
+
262
+ 1. Select layout entry files using the mode above.
263
+ 2. From each root layout's **`render` client graph** (reachability analysis), follow relative imports and tsconfig path aliases. Type-only imports and `.server.ts` modules are skipped.
264
+ 3. Collect npm package roots (for example `@tanstack/react-query`, not `@tanstack/react-query/devtools`).
265
+ 4. Register each discovered package as a shared vendor.
266
+
267
+ **Excluded automatically:** React, React DOM, jsx runtimes, the router bundle, `@ecopages/*`, workspace packages under `@techn.es/*`, `*-devtools` packages, and packages already vendored by the React plugin.
268
+
269
+ Path aliases resolve from `tsconfig.json` `compilerOptions.paths` (oxc-resolver), same as the Ecopages alias resolver plugin.
270
+
271
+ #### Recommended setup
272
+
273
+ Plugin config — no manual vendor list when provider layouts are flagged:
274
+
275
+ ```ts
276
+ import { ConfigBuilder } from '@ecopages/core/config-builder';
277
+ import { reactPlugin } from '@ecopages/react';
278
+ import { ecoRouter } from '@ecopages/react-router';
279
+
280
+ const config = await new ConfigBuilder().setIntegrations([reactPlugin({ router: ecoRouter() })]).build();
281
+
282
+ export default config;
283
+ ```
284
+
285
+ Provider root layout — set `runtimeProvider: true` on the tier that mounts shared client state:
286
+
287
+ ```tsx
288
+ import type { ReactNode } from 'react';
289
+ import { eco } from '@ecopages/core';
290
+ import { QueryProvider } from '@/shared/query/query-provider';
291
+
292
+ export const QueryRootLayout = eco.layout<ReactNode>({
293
+ runtimeProvider: true,
294
+ render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
295
+ });
296
+ ```
297
+
298
+ Shell layouts that do not mount shared runtime state omit the flag:
299
+
300
+ ```tsx
301
+ export const AppShellLayout = eco.layout({
302
+ render: ({ children }) => <AppShell>{children}</AppShell>,
303
+ });
304
+ ```
305
+
306
+ Stack provider roots before shell tiers in page `layout` arrays so context wraps the shell on both SSR and persisted client navigation.
307
+
308
+ Requires matching tsconfig paths when using aliases:
309
+
310
+ ```json
311
+ {
312
+ "compilerOptions": {
313
+ "paths": {
314
+ "@/*": ["./src/*"]
315
+ }
316
+ }
317
+ }
318
+ ```
319
+
320
+ #### Overrides and escape hatches
321
+
322
+ Use explicit `runtimeModules` when discovery misses a package, when `router` is not enabled, or when you need custom vendor output names or externals:
323
+
324
+ ```ts
325
+ reactPlugin({
326
+ router: ecoRouter(),
327
+ runtimeModules: ['@tanstack/react-query', { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] }],
328
+ });
329
+ ```
330
+
331
+ Manual entries **override** auto-discovered entries for the same specifier.
332
+
333
+ #### Troubleshooting
334
+
335
+ | Symptom | Likely cause | Fix |
336
+ | ------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
337
+ | `No QueryClient set` after SPA navigation | Provider library bundled per page chunk | Ensure `router` is enabled; add `runtimeProvider: true` on the provider layout; rebuild vendors |
338
+ | Wrong packages vendored (slow dev startup) | Shell layout scanned as discovery root | Set `runtimeProvider: true` only on provider roots; keep shell layouts unflagged |
339
+ | Package not discovered | Layout outside `layouts/` / `components/`, or import not reachable from `render` | Move layout file or add explicit `runtimeModules` entry |
340
+ | `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
341
+
342
+ #### Tests
343
+
344
+ - [src/bundling/discover-layout-runtime-modules.test.ts](src/bundling/discover-layout-runtime-modules.test.ts): discovery modes, provider scoping, tsconfig aliases, stacked layouts.
345
+ - [src/bundling/runtime-bundle.test.ts](src/bundling/runtime-bundle.test.ts): vendor registration and manifest paths.
346
+ - [../../core/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.test.ts](../../core/src/services/assets/asset-processing-service/browser-runtime-entry-resolution.test.ts): ESM entry resolution and default-export policy for React vs TanStack Query.
347
+
348
+ ### Client-only code in SSR trees
349
+
350
+ Pages and layouts SSR through `renderToString`, which does not support `<Suspense>`. Do not use `React.lazy()` + `<Suspense>` in `eco.page()` or `eco.layout()` trees.
351
+
352
+ Wrap browser-only UI in `ClientOnly`:
353
+
354
+ ```tsx
355
+ import { eco } from '@ecopages/core';
356
+ import { ClientOnly } from '@ecopages/react/utils/client-only';
357
+
358
+ export const RootLayout = eco.layout({
359
+ render: ({ children }) => (
360
+ <>
361
+ {children}
362
+ <ClientOnly fallback={null}>
363
+ <DevtoolsPanel />
364
+ </ClientOnly>
365
+ </>
366
+ ),
367
+ });
368
+ ```
369
+
370
+ For code-split client-only modules, `import()` inside `useEffect` within `ClientOnly` — not `lazy()`. `dynamic({ ssr: false })` must also stay inside `ClientOnly`; it renders `null` on the server and `lazy()` in the browser.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.2.0-beta.3",
3
+ "version": "0.2.0-beta.30",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -8,76 +8,101 @@
8
8
  "plugin"
9
9
  ],
10
10
  "license": "MIT",
11
- "main": "./src/react.plugin.js",
12
- "types": "./src/react.plugin.d.ts",
11
+ "main": "./src/plugin/react.plugin.js",
12
+ "types": "./src/plugin/react.plugin.d.ts",
13
13
  "type": "module",
14
14
  "exports": {
15
15
  ".": {
16
- "default": "./src/react.plugin.js",
17
- "types": "./src/react.plugin.d.ts"
16
+ "default": "./src/plugin/react.plugin.js",
17
+ "types": "./src/plugin/react.plugin.d.ts"
18
18
  },
19
19
  "./eco-embed": {
20
- "default": "./src/eco-embed.js",
21
- "types": "./src/eco-embed.d.ts"
20
+ "default": "./src/render/eco-embed.js",
21
+ "types": "./src/render/eco-embed.d.ts"
22
22
  },
23
23
  "./declarations": {
24
- "types": "./src/declarations.d.ts"
24
+ "types": "./src/contracts/declarations.d.ts"
25
25
  },
26
26
  "./utils/dynamic": {
27
- "types": "./src/utils/dynamic.d.ts",
28
- "default": "./src/utils/dynamic.js"
27
+ "types": "./src/app/dynamic.d.ts",
28
+ "default": "./src/app/dynamic.js"
29
29
  },
30
30
  "./utils/client-only": {
31
- "types": "./src/utils/client-only.d.ts",
32
- "default": "./src/utils/client-only.js"
31
+ "types": "./src/app/client-only.d.ts",
32
+ "default": "./src/app/client-only.js"
33
33
  },
34
34
  "./runtime/use-sync-external-store-with-selector": {
35
35
  "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
36
36
  "default": "./src/runtime/use-sync-external-store-with-selector.js"
37
37
  },
38
38
  "./router-adapter": {
39
- "types": "./src/router-adapter.d.ts",
40
- "default": "./src/router-adapter.js"
39
+ "types": "./src/contracts/router-adapter.d.ts",
40
+ "default": "./src/contracts/router-adapter.js"
41
+ },
42
+ "./layout-compose": {
43
+ "types": "./src/render/layout-compose.d.ts",
44
+ "default": "./src/render/layout-compose.js"
45
+ },
46
+ "./serialize-page-data-script": {
47
+ "types": "./src/hydration/serialize-page-data-script.d.ts",
48
+ "default": "./src/hydration/serialize-page-data-script.js"
49
+ },
50
+ "./page-data-reader": {
51
+ "types": "./src/hydration/page-data-reader.d.ts",
52
+ "default": "./src/hydration/page-data-reader.js"
41
53
  },
42
54
  "./eco-embed.ts": {
43
- "default": "./src/eco-embed.js",
44
- "types": "./src/eco-embed.d.ts"
55
+ "default": "./src/render/eco-embed.js",
56
+ "types": "./src/render/eco-embed.d.ts"
45
57
  },
46
58
  "./declarations.ts": {
47
- "types": "./src/declarations.d.ts"
59
+ "types": "./src/contracts/declarations.d.ts"
48
60
  },
49
61
  "./utils/dynamic.ts": {
50
- "types": "./src/utils/dynamic.d.ts",
51
- "default": "./src/utils/dynamic.js"
62
+ "types": "./src/app/dynamic.d.ts",
63
+ "default": "./src/app/dynamic.js"
52
64
  },
53
65
  "./utils/client-only.ts": {
54
- "types": "./src/utils/client-only.d.ts",
55
- "default": "./src/utils/client-only.js"
66
+ "types": "./src/app/client-only.d.ts",
67
+ "default": "./src/app/client-only.js"
56
68
  },
57
69
  "./runtime/use-sync-external-store-with-selector.ts": {
58
70
  "types": "./src/runtime/use-sync-external-store-with-selector.d.ts",
59
71
  "default": "./src/runtime/use-sync-external-store-with-selector.js"
60
72
  },
61
73
  "./router-adapter.ts": {
62
- "types": "./src/router-adapter.d.ts",
63
- "default": "./src/router-adapter.js"
74
+ "types": "./src/contracts/router-adapter.d.ts",
75
+ "default": "./src/contracts/router-adapter.js"
76
+ },
77
+ "./layout-compose.ts": {
78
+ "types": "./src/render/layout-compose.d.ts",
79
+ "default": "./src/render/layout-compose.js"
80
+ },
81
+ "./serialize-page-data-script.ts": {
82
+ "types": "./src/hydration/serialize-page-data-script.d.ts",
83
+ "default": "./src/hydration/serialize-page-data-script.js"
84
+ },
85
+ "./page-data-reader.ts": {
86
+ "types": "./src/hydration/page-data-reader.d.ts",
87
+ "default": "./src/hydration/page-data-reader.js"
64
88
  }
65
89
  },
66
90
  "repository": {
67
91
  "type": "git",
68
- "url": "https://github.com/ecopages/ecopages.git",
92
+ "url": "git+https://github.com/ecopages/ecopages.git",
69
93
  "directory": "packages/integrations/react"
70
94
  },
71
95
  "peerDependencies": {
72
- "@ecopages/core": "0.2.0-beta.3",
96
+ "@ecopages/core": "0.2.0-beta.30",
73
97
  "@types/react": "^19",
74
98
  "@types/react-dom": "^19",
75
99
  "react": "^19",
76
100
  "react-dom": "^19"
77
101
  },
78
102
  "dependencies": {
79
- "@ecopages/file-system": "0.2.0-beta.3",
103
+ "@ecopages/file-system": "0.2.0-beta.30",
80
104
  "@ecopages/logger": "^0.2.3",
105
+ "@ecopages/mdx": "0.2.0-beta.30",
81
106
  "@mdx-js/mdx": "^3.1.1",
82
107
  "oxc-parser": "^0.124.0",
83
108
  "oxc-transform": "^0.124.0",
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Bare package specifiers for React page hydration bootstrap helpers.
3
+ */
4
+ export declare const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/eco/page-layout-normalization";
5
+ export declare const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
@@ -0,0 +1,6 @@
1
+ const PAGE_LAYOUT_NORMALIZATION_PACKAGE = "@ecopages/core/eco/page-layout-normalization";
2
+ const LAYOUT_COMPOSE_PACKAGE = "@ecopages/react/layout-compose";
3
+ export {
4
+ LAYOUT_COMPOSE_PACKAGE,
5
+ PAGE_LAYOUT_NORMALIZATION_PACKAGE
6
+ };
@@ -6,18 +6,22 @@
6
6
  *
7
7
  * @module
8
8
  */
9
- import type { ReactRouterAdapter } from '../router-adapter.js';
9
+ import type { EcoPagesAppConfig } from '@ecopages/core';
10
+ import type { AssetProcessingService } from '@ecopages/core/services/asset-processing-service';
11
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
10
12
  import type { CompileOptions } from '@mdx-js/mdx';
11
- import { type ReactRuntimeImports } from './react-runtime-bundle.service.js';
13
+ import { type ReactRuntimeImports } from './runtime-bundle.js';
14
+ import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
12
15
  /**
13
- * Configuration for the ReactBundleService.
16
+ * Configuration for the BundleService.
14
17
  */
15
- export interface ReactBundleServiceConfig {
18
+ export interface BundleServiceConfig {
16
19
  rootDir: string;
20
+ appConfig: EcoPagesAppConfig;
21
+ hostIntegrationName: string;
17
22
  routerAdapter?: ReactRouterAdapter;
23
+ runtimeModules?: ResolvedReactPluginRuntimeModule[];
18
24
  mdxCompilerOptions?: CompileOptions;
19
- nonReactExtensions?: string[];
20
- jsxImportSource?: string;
21
25
  }
22
26
  /**
23
27
  * Optional flags that adjust how a React client entry is bundled.
@@ -36,14 +40,23 @@ export interface ReactClientBundleOptions {
36
40
  /**
37
41
  * Manages bundle configuration and plugin creation for React page/component builds.
38
42
  */
39
- export declare class ReactBundleService {
43
+ export declare class BundleService {
40
44
  private readonly runtimeBundleService;
41
45
  private readonly config;
42
- constructor(config: ReactBundleServiceConfig);
46
+ private pageLayoutNormalizationVendorPromise;
47
+ constructor(config: BundleServiceConfig);
43
48
  /**
44
49
  * Returns resolved runtime import paths for the React runtime.
45
50
  */
46
51
  getRuntimeImports(): ReactRuntimeImports;
52
+ /**
53
+ * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
54
+ *
55
+ * @remarks
56
+ * Concurrent callers share the same in-flight promise. Asset processing itself caches
57
+ * by dependency key, so repeats after success remain cheap.
58
+ */
59
+ ensurePageLayoutNormalizationVendorProcessed(assetProcessingService: Pick<AssetProcessingService, 'processDependencies'>): Promise<void>;
47
60
  /**
48
61
  * Creates bundle options for a page or component entry.
49
62
  *
@@ -1,20 +1,20 @@
1
- import { createClientGraphBoundaryPlugin } from "../utils/client-graph-boundary-plugin.js";
2
- import {
3
- getReactClientGraphAllowSpecifiers,
4
- getReactRuntimeExternalSpecifiers
5
- } from "../utils/react-runtime-alias-map.js";
1
+ import { createClientGraphBoundaryPlugin } from "../client-graph/boundary-plugin.js";
2
+ import { getReactClientGraphAllowSpecifiers, getReactRuntimeExternalSpecifiers } from "./runtime-alias-map.js";
6
3
  import { createBrowserRuntimePlugin } from "@ecopages/core/build/browser-runtime-plugin";
7
- import { createForeignJsxOverridePlugin } from "@ecopages/core/plugins/foreign-jsx-override-plugin";
8
- import { ReactRuntimeBundleService } from "./react-runtime-bundle.service.js";
9
- import { createReactMdxLoaderPlugin } from "../utils/react-mdx-loader-plugin.js";
10
- class ReactBundleService {
4
+ import { getHostScopedJsxOwnershipPlugins } from "@ecopages/core/build/jsx-ownership-plugins";
5
+ import { RuntimeBundleService } from "./runtime-bundle.js";
6
+ import { createReactMdxLoaderPlugin } from "../mdx/mdx-loader-plugin.js";
7
+ import { isReactProductionRuntime } from "./runtime-mode.js";
8
+ class BundleService {
11
9
  runtimeBundleService;
12
10
  config;
11
+ pageLayoutNormalizationVendorPromise;
13
12
  constructor(config) {
14
13
  this.config = config;
15
- this.runtimeBundleService = new ReactRuntimeBundleService({
14
+ this.runtimeBundleService = new RuntimeBundleService({
16
15
  rootDir: config.rootDir,
17
- routerAdapter: config.routerAdapter
16
+ routerAdapter: config.routerAdapter,
17
+ runtimeModules: config.runtimeModules
18
18
  });
19
19
  }
20
20
  /**
@@ -23,6 +23,25 @@ class ReactBundleService {
23
23
  getRuntimeImports() {
24
24
  return this.runtimeBundleService.getRuntimeImports();
25
25
  }
26
+ /**
27
+ * Processes the MDX-only page-layout-normalization vendor once per BundleService instance.
28
+ *
29
+ * @remarks
30
+ * Concurrent callers share the same in-flight promise. Asset processing itself caches
31
+ * by dependency key, so repeats after success remain cheap.
32
+ */
33
+ async ensurePageLayoutNormalizationVendorProcessed(assetProcessingService) {
34
+ if (!this.pageLayoutNormalizationVendorPromise) {
35
+ this.pageLayoutNormalizationVendorPromise = assetProcessingService.processDependencies(
36
+ this.runtimeBundleService.getPageLayoutNormalizationDependencies(),
37
+ "react:page-layout-normalization"
38
+ ).then(() => void 0).catch((error) => {
39
+ this.pageLayoutNormalizationVendorPromise = void 0;
40
+ throw error;
41
+ });
42
+ }
43
+ await this.pageLayoutNormalizationVendorPromise;
44
+ }
26
45
  /**
27
46
  * Creates bundle options for a page or component entry.
28
47
  *
@@ -40,7 +59,7 @@ class ReactBundleService {
40
59
  const options = {
41
60
  mainFields: ["module", "browser", "main"],
42
61
  naming: `${componentName}.[ext]`,
43
- ...import.meta.env?.NODE_ENV === "production" && {
62
+ ...isReactProductionRuntime() && {
44
63
  minify: true,
45
64
  treeshaking: true
46
65
  },
@@ -57,15 +76,19 @@ class ReactBundleService {
57
76
  ];
58
77
  }
59
78
  const graphBoundaryPlugin = createClientGraphBoundaryPlugin({
79
+ projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
60
80
  absWorkingDir: this.config.rootDir,
61
81
  declaredModules,
62
- alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers([], this.config.routerAdapter)
63
- });
64
- const foreignJsxOverridePlugin = createForeignJsxOverridePlugin({
65
- name: "react-renderer-foreign-jsx-override",
66
- hostJsxImportSource: this.config.jsxImportSource ?? "react",
67
- foreignExtensions: this.config.nonReactExtensions ?? []
82
+ alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(
83
+ this.runtimeBundleService.getConfiguredRuntimeModuleSpecifiers(),
84
+ this.config.routerAdapter
85
+ )
68
86
  });
87
+ const [foreignJsxOverridePlugin] = getHostScopedJsxOwnershipPlugins(
88
+ this.config.appConfig,
89
+ this.config.hostIntegrationName,
90
+ { name: "react-renderer-foreign-jsx-override" }
91
+ );
69
92
  const runtimeManifest = this.runtimeBundleService.getRuntimeManifest();
70
93
  const runtimeRewritePlugin = createBrowserRuntimePlugin({
71
94
  name: "react-renderer-runtime-import-rewrite",
@@ -74,13 +97,22 @@ class ReactBundleService {
74
97
  const runtimePlugins = bundleOptions.includeRuntime ? [] : [runtimeRewritePlugin].filter((plugin) => plugin !== null);
75
98
  if (isMdx && this.config.mdxCompilerOptions) {
76
99
  const mdxPlugin = createReactMdxLoaderPlugin(this.config.mdxCompilerOptions);
77
- options.plugins = [foreignJsxOverridePlugin, graphBoundaryPlugin, ...runtimePlugins, mdxPlugin];
100
+ options.plugins = [
101
+ ...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
102
+ graphBoundaryPlugin,
103
+ ...runtimePlugins,
104
+ mdxPlugin
105
+ ];
78
106
  } else {
79
- options.plugins = [foreignJsxOverridePlugin, graphBoundaryPlugin, ...runtimePlugins];
107
+ options.plugins = [
108
+ ...foreignJsxOverridePlugin ? [foreignJsxOverridePlugin] : [],
109
+ graphBoundaryPlugin,
110
+ ...runtimePlugins
111
+ ];
80
112
  }
81
113
  return options;
82
114
  }
83
115
  }
84
116
  export {
85
- ReactBundleService
117
+ BundleService
86
118
  };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Discovers npm packages reachable from persisted `eco.layout()` client graphs.
3
+ *
4
+ * @module
5
+ */
6
+ export type LayoutRuntimeDiscoveryMode = 'runtime-provider-layouts' | 'provider-scoped-fallback';
7
+ export type LayoutRuntimeDiscoveryResult = {
8
+ specifiers: string[];
9
+ mode: LayoutRuntimeDiscoveryMode;
10
+ };
11
+ /**
12
+ * Returns true when a layout opts into runtime-provider auto-vendoring discovery.
13
+ */
14
+ export declare function isRuntimeProviderLayoutSource(source: string): boolean;
15
+ /**
16
+ * Returns true when a module looks like it mounts shared client runtime state
17
+ * (React context providers, query clients, etc.).
18
+ */
19
+ export declare function isProviderRuntimeModulePath(filePath: string, source: string): boolean;
20
+ /**
21
+ * Normalizes import specifiers to the package entry used for browser vendors.
22
+ */
23
+ export declare function normalizeRuntimePackageSpecifier(specifier: string): string;
24
+ /**
25
+ * Finds npm packages imported from persisted layout client graphs under the given directories.
26
+ */
27
+ export declare function discoverLayoutRuntimeModuleSpecifiers(options: {
28
+ searchDirs: string[];
29
+ projectRoot?: string;
30
+ extensions?: readonly string[];
31
+ routerImportPath?: string;
32
+ }): LayoutRuntimeDiscoveryResult;