@ecopages/react 0.2.1-beta.0 → 0.3.0

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 (181) hide show
  1. package/README.md +164 -28
  2. package/package.json +67 -30
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.js +38 -0
  6. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  7. package/src/bundling/bootstrap-package-paths.js +5 -0
  8. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +29 -11
  9. package/src/bundling/bundle.js +130 -0
  10. package/src/bundling/runtime-alias-map.d.ts +12 -0
  11. package/src/bundling/runtime-alias-map.js +110 -0
  12. package/src/bundling/runtime-bundle.d.ts +70 -0
  13. package/src/bundling/runtime-bundle.js +233 -0
  14. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  15. package/src/bundling/runtime-interop-plugin.js +32 -0
  16. package/src/bundling/runtime-mode.d.ts +1 -0
  17. package/src/bundling/runtime-mode.js +10 -0
  18. package/src/bundling/runtime-modules.d.ts +21 -0
  19. package/src/bundling/runtime-modules.js +28 -0
  20. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  21. package/src/client-graph/ast-transform-eco-page.js +71 -0
  22. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  23. package/src/client-graph/ast-transform-import-edits.js +75 -0
  24. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  25. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  26. package/src/client-graph/ast-transform.d.ts +12 -0
  27. package/src/client-graph/ast-transform.js +91 -0
  28. package/src/client-graph/ast-walk.d.ts +10 -0
  29. package/src/client-graph/ast-walk.js +26 -0
  30. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  31. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  32. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  33. package/src/client-graph/boundary-plugin-transform.js +31 -0
  34. package/src/client-graph/boundary-plugin.d.ts +23 -0
  35. package/src/client-graph/boundary-plugin.js +177 -0
  36. package/src/client-graph/component-config-traversal.js +77 -0
  37. package/src/client-graph/declared-modules.js +69 -0
  38. package/src/client-graph/module-classification.d.ts +3 -0
  39. package/src/client-graph/module-classification.js +43 -0
  40. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  41. package/src/client-graph/reachability-analyzer.js +55 -0
  42. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  43. package/src/client-graph/reachability-client-roots.js +59 -0
  44. package/src/client-graph/reachability-export-names.d.ts +5 -0
  45. package/src/client-graph/reachability-export-names.js +34 -0
  46. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  47. package/src/client-graph/reachability-fallback-roots.js +71 -0
  48. package/src/client-graph/reachability-preload.d.ts +10 -0
  49. package/src/client-graph/reachability-preload.js +30 -0
  50. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  51. package/src/client-graph/reachability-top-level-index.js +93 -0
  52. package/src/client-graph/reachability-traverse.d.ts +7 -0
  53. package/src/client-graph/reachability-traverse.js +201 -0
  54. package/src/client-graph/specifier-classification.d.ts +74 -0
  55. package/src/client-graph/specifier-classification.js +191 -0
  56. package/src/content/collection-component-cache.d.ts +25 -0
  57. package/src/content/collection-component-cache.js +62 -0
  58. package/src/contracts/router-adapter.js +6 -0
  59. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  60. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  61. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  62. package/src/hmr/hmr-strategy-process.js +83 -0
  63. package/src/hmr/hmr-strategy.d.ts +67 -0
  64. package/src/hmr/hmr-strategy.js +306 -0
  65. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  66. package/src/hmr/page-metadata-cache.js +44 -0
  67. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  68. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  69. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  70. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  71. package/src/hydration/bootstrap-imports.d.ts +25 -0
  72. package/src/hydration/bootstrap-imports.js +33 -0
  73. package/src/hydration/browser/island-hydration.d.ts +82 -0
  74. package/src/hydration/browser/island-hydration.js +251 -0
  75. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  76. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  77. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  78. package/src/hydration/browser/page-hydration-module.js +17 -0
  79. package/src/hydration/browser/page-hydration.d.ts +54 -0
  80. package/src/hydration/browser/page-hydration.js +177 -0
  81. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  82. package/src/hydration/hydration-asset.d.ts +127 -0
  83. package/src/hydration/hydration-asset.js +379 -0
  84. package/src/hydration/hydration-lifecycle.test.browser.d.ts +1 -0
  85. package/src/hydration/hydration-lifecycle.test.browser.js +461 -0
  86. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  87. package/src/hydration/hydration-page-entry-source.js +87 -0
  88. package/src/hydration/hydration-script-compiler.d.ts +48 -0
  89. package/src/hydration/hydration-script-compiler.js +213 -0
  90. package/src/hydration/page-data-manifest.d.ts +58 -0
  91. package/src/hydration/page-data-manifest.js +97 -0
  92. package/src/hydration/page-data-reader.d.ts +17 -0
  93. package/src/hydration/page-data-reader.js +31 -0
  94. package/src/hydration/page-payload.d.ts +68 -0
  95. package/src/hydration/page-payload.js +106 -0
  96. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  97. package/src/hydration/serialize-page-data-script.js +30 -0
  98. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +9 -8
  99. package/src/mdx/mdx-config-dependency.js +107 -0
  100. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  101. package/src/mdx/mdx-loader-plugin.js +11 -0
  102. package/src/page/page-module.d.ts +46 -0
  103. package/src/page/page-module.js +74 -0
  104. package/src/plugin/react.constants.js +1 -0
  105. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +21 -27
  106. package/src/plugin/react.plugin.js +210 -0
  107. package/src/plugin/react.types.d.ts +106 -0
  108. package/src/plugin/react.types.js +1 -0
  109. package/src/render/component-ownership.d.ts +49 -0
  110. package/src/render/component-ownership.js +47 -0
  111. package/src/render/component-ssr.d.ts +59 -0
  112. package/src/render/component-ssr.js +76 -0
  113. package/src/render/eco-embed.js +9 -0
  114. package/src/render/errors.d.ts +16 -0
  115. package/src/render/errors.js +23 -0
  116. package/src/render/html-boundary.js +59 -0
  117. package/src/render/layout-compose.d.ts +66 -0
  118. package/src/render/layout-compose.js +134 -0
  119. package/src/render/react-renderer.d.ts +114 -0
  120. package/src/render/react-renderer.js +490 -0
  121. package/src/render/react-runtime.d.ts +13 -0
  122. package/src/render/react-runtime.js +26 -0
  123. package/src/render/unified-layout-composition.d.ts +22 -0
  124. package/src/render/unified-layout-composition.js +31 -0
  125. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
  126. package/src/eco-embed.js +0 -11
  127. package/src/react-hmr-strategy.d.ts +0 -230
  128. package/src/react-hmr-strategy.js +0 -657
  129. package/src/react-renderer.d.ts +0 -233
  130. package/src/react-renderer.js +0 -622
  131. package/src/react.constants.js +0 -4
  132. package/src/react.plugin.js +0 -205
  133. package/src/react.types.d.ts +0 -88
  134. package/src/react.types.js +0 -0
  135. package/src/router-adapter.js +0 -0
  136. package/src/services/pages-index.d.ts +0 -64
  137. package/src/services/pages-index.js +0 -73
  138. package/src/services/react-bundle.service.js +0 -86
  139. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  140. package/src/services/react-hydration-asset.service.d.ts +0 -84
  141. package/src/services/react-hydration-asset.service.js +0 -217
  142. package/src/services/react-mdx-config-dependency.service.js +0 -122
  143. package/src/services/react-page-module.service.d.ts +0 -88
  144. package/src/services/react-page-module.service.js +0 -166
  145. package/src/services/react-page-payload.service.d.ts +0 -46
  146. package/src/services/react-page-payload.service.js +0 -67
  147. package/src/services/react-runtime-bundle.service.d.ts +0 -45
  148. package/src/services/react-runtime-bundle.service.js +0 -186
  149. package/src/utils/client-graph-boundary-cache.d.ts +0 -108
  150. package/src/utils/client-graph-boundary-cache.js +0 -116
  151. package/src/utils/client-graph-boundary-plugin.d.ts +0 -51
  152. package/src/utils/client-graph-boundary-plugin.js +0 -552
  153. package/src/utils/client-only.js +0 -19
  154. package/src/utils/component-config-traversal.js +0 -54
  155. package/src/utils/declared-modules.js +0 -47
  156. package/src/utils/dynamic.js +0 -12
  157. package/src/utils/dynamic.test.browser.js +0 -33
  158. package/src/utils/hmr-scripts.d.ts +0 -18
  159. package/src/utils/hmr-scripts.js +0 -31
  160. package/src/utils/html-boundary.js +0 -55
  161. package/src/utils/hydration-scripts.d.ts +0 -92
  162. package/src/utils/hydration-scripts.js +0 -358
  163. package/src/utils/hydration-scripts.test.browser.js +0 -198
  164. package/src/utils/reachability-analyzer.d.ts +0 -66
  165. package/src/utils/reachability-analyzer.js +0 -339
  166. package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
  167. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  168. package/src/utils/react-mdx-loader-plugin.js +0 -45
  169. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  170. package/src/utils/react-runtime-alias-map.js +0 -90
  171. /package/src/{utils → app}/client-only.d.ts +0 -0
  172. /package/src/{utils → app}/dynamic.d.ts +0 -0
  173. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  174. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  175. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  176. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  177. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  178. /package/src/{utils/hydration-scripts.test.browser.d.ts → hydration/compiled-page-hydration-options.js} +0 -0
  179. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  180. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  181. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,106 @@
1
+ import type { AssetDefinition } from '@ecopages/core/integration';
2
+ import type { EcoBuildPlugin } from '@ecopages/core/integration';
3
+ import type { MdxCompilerOptionsInput } from '@ecopages/mdx/core';
4
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
5
+ import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
6
+ import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from '../bundling/runtime-modules.js';
7
+ export type ReactMdxOptions = MdxCompilerOptionsInput;
8
+ /**
9
+ * Options for the React plugin.
10
+ */
11
+ export type ReactPluginOptions = {
12
+ extensions?: string[];
13
+ dependencies?: AssetDefinition[];
14
+ /**
15
+ * When true, always emit the page browser graph / hydration assets for React
16
+ * page entries, even when the page does not declare `dependencies.modules`
17
+ * and no router adapter is configured.
18
+ *
19
+ * @remarks
20
+ * This does not skip the client-graph AST boundary. Server-only
21
+ * `eco.page(...)` options such as `middleware` and `requires` are still
22
+ * stripped from browser bundles.
23
+ *
24
+ * With a router adapter, page hydration is already always enabled, so this
25
+ * option is redundant for SPA apps.
26
+ *
27
+ * @default false
28
+ */
29
+ explicitGraph?: boolean;
30
+ /**
31
+ * Router adapter for SPA navigation.
32
+ * When provided, pages with layouts will be wrapped in the router for client-side navigation.
33
+ * @example
34
+ * ```ts
35
+ * import { ecoRouter } from '@ecopages/react-router';
36
+ * reactPlugin({ router: ecoRouter() })
37
+ * ```
38
+ */
39
+ router?: ReactRouterAdapter;
40
+ /**
41
+ * Optional shared browser runtime vendors.
42
+ *
43
+ * @remarks
44
+ * Packages listed here use one vendor URL across page browser graphs. Add
45
+ * singleton packages such as TanStack Query or MobX when pages and layouts
46
+ * need to share the same module instance; layouts do not infer these entries.
47
+ *
48
+ * @example
49
+ * ```ts
50
+ * reactPlugin({
51
+ * router: ecoRouter(),
52
+ * runtimeModules: ['@tanstack/react-query'],
53
+ * });
54
+ * ```
55
+ *
56
+ * Register the exact specifier imported by the page or layout. Package
57
+ * subpaths are separate module contracts and need separate entries.
58
+ *
59
+ * @example Advanced vendor config
60
+ * ```ts
61
+ * runtimeModules: [
62
+ * { specifier: '@acme/ui', outputName: 'acme-ui' },
63
+ * ]
64
+ * ```
65
+ */
66
+ runtimeModules?: ReactPluginRuntimeModule[];
67
+ /**
68
+ * MDX configuration for handling .mdx files within the React plugin.
69
+ * When configured, MDX files are treated as React pages with full router support.
70
+ * @example
71
+ * ```ts
72
+ * reactPlugin({
73
+ * router: ecoRouter(),
74
+ * mdx: {
75
+ * extensions: ['.mdx', '.md'],
76
+ * remarkPlugins: [remarkGfm],
77
+ * rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
78
+ * }
79
+ * })
80
+ * ```
81
+ */
82
+ mdx?: ReactMdxOptions;
83
+ };
84
+ export type ReactRendererConfig = {
85
+ routerAdapter?: ReactRouterAdapter;
86
+ runtimeModules?: ResolvedReactPluginRuntimeModule[];
87
+ /**
88
+ * Returns the plugin-owned MDX loader, creating it on first call. Set only
89
+ * when MDX is enabled.
90
+ *
91
+ * @remarks
92
+ * Server builds, browser bundles and HMR rebuilds all use this one loader, so
93
+ * they share its compile cache.
94
+ */
95
+ getMdxLoaderPlugin?: () => EcoBuildPlugin;
96
+ mdxExtensions?: string[];
97
+ hmrPageMetadataCache?: HmrPageMetadataCache;
98
+ /**
99
+ * When true, always emit page browser graph / hydration assets for React pages.
100
+ *
101
+ * @remarks
102
+ * Mapped from the public `explicitGraph` plugin option. Does not skip the
103
+ * client-graph AST strip of server-only `eco.page(...)` options.
104
+ */
105
+ forceBrowserGraph?: boolean;
106
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Ownership helpers for deciding whether a component stays in the React render lane.
3
+ */
4
+ import type { EcoComponent, EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
5
+ import type { FunctionComponent } from 'react';
6
+ export type SerializableProps = Record<string, unknown>;
7
+ export type ReactRenderableComponent<P extends SerializableProps = SerializableProps> = FunctionComponent<P> & {
8
+ config?: EcoComponentConfig;
9
+ requires?: string | readonly string[];
10
+ };
11
+ export type RequiresAwareComponent = {
12
+ requires?: string | readonly string[];
13
+ };
14
+ /**
15
+ * Reads the declared integration name for a component or layout.
16
+ *
17
+ * @remarks
18
+ * Honors both the explicit `config.integration` override and build-time
19
+ * `getComponentIdentity(component)?.integration` attribution.
20
+ */
21
+ export declare function getComponentIntegration(component?: {
22
+ config?: EcoComponentConfig;
23
+ } | null): string | undefined;
24
+ /**
25
+ * Returns whether a component should stay inside the React render lane.
26
+ *
27
+ * @remarks
28
+ * Components without explicit integration metadata are treated as React-owned
29
+ * because this renderer only receives them after the route pipeline has already
30
+ * selected the React integration.
31
+ */
32
+ export declare function isReactManagedComponent(component: {
33
+ config?: EcoComponentConfig;
34
+ } | null | undefined, reactIntegrationName: string): boolean;
35
+ export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
36
+ /**
37
+ * Commits a framework-agnostic component to React semantics.
38
+ *
39
+ * @remarks
40
+ * Core keeps `EcoComponent` broad so integrations can share the same public surface;
41
+ * once the React renderer is executing, `createElement()` needs a concrete React
42
+ * component signature.
43
+ */
44
+ export declare function asReactComponent<P extends SerializableProps>(component: unknown): ReactRenderableComponent<P>;
45
+ /**
46
+ * Commits a mixed-shell component to the string-returning contract required by
47
+ * non-React layouts and HTML templates.
48
+ */
49
+ export declare function asNonReactShellComponent<P extends SerializableProps>(component: unknown): (props: P) => EcoPagesElement | Promise<EcoPagesElement>;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Ownership helpers for deciding whether a component stays in the React render lane.
3
+ */
4
+ import { getComponentOwner } from '@ecopages/core';
5
+ /**
6
+ * Reads the declared integration name for a component or layout.
7
+ *
8
+ * @remarks
9
+ * Honors both the explicit `config.integration` override and build-time
10
+ * `getComponentIdentity(component)?.integration` attribution.
11
+ */
12
+ export function getComponentIntegration(component) {
13
+ return getComponentOwner(component?.config);
14
+ }
15
+ /**
16
+ * Returns whether a component should stay inside the React render lane.
17
+ *
18
+ * @remarks
19
+ * Components without explicit integration metadata are treated as React-owned
20
+ * because this renderer only receives them after the route pipeline has already
21
+ * selected the React integration.
22
+ */
23
+ export function isReactManagedComponent(component, reactIntegrationName) {
24
+ const integration = getComponentIntegration(component);
25
+ return integration === undefined || integration === reactIntegrationName;
26
+ }
27
+ export function getComponentRequires(component) {
28
+ return component?.requires;
29
+ }
30
+ /**
31
+ * Commits a framework-agnostic component to React semantics.
32
+ *
33
+ * @remarks
34
+ * Core keeps `EcoComponent` broad so integrations can share the same public surface;
35
+ * once the React renderer is executing, `createElement()` needs a concrete React
36
+ * component signature.
37
+ */
38
+ export function asReactComponent(component) {
39
+ return component;
40
+ }
41
+ /**
42
+ * Commits a mixed-shell component to the string-returning contract required by
43
+ * non-React layouts and HTML templates.
44
+ */
45
+ export function asNonReactShellComponent(component) {
46
+ return component;
47
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * React component SSR helpers: renderToString, foreign-subtree HTML, island attributes.
3
+ */
4
+ /**
5
+ * React component SSR helpers: renderToString, foreign-subtree HTML, island attributes.
6
+ */
7
+ import type { EcoComponent, EcoPagesElement } from '@ecopages/core';
8
+ import type { ComponentRenderInput } from '@ecopages/core/integration';
9
+ import type { IntegrationRenderer } from '@ecopages/core/integration';
10
+ import type { ReactNode } from 'react';
11
+ import { type SerializableProps } from './component-ownership.js';
12
+ import type { ReactRuntimeModules } from './react-runtime.js';
13
+ export type ReactComponentRenderContext = {
14
+ componentInstanceId?: string;
15
+ };
16
+ export type ReactForeignSubtreeResolutionContext = {
17
+ rendererCache: Map<string, IntegrationRenderer<any>>;
18
+ componentInstanceScope?: string;
19
+ nextForeignSubtreeId: number;
20
+ queuedResolutions: Array<{
21
+ token: string;
22
+ component: EcoComponent;
23
+ props: Record<string, unknown>;
24
+ componentInstanceId: string;
25
+ }>;
26
+ rawChildrenToken?: string;
27
+ rawChildrenHtml?: string;
28
+ };
29
+ export declare function buildHydrationProps(props: SerializableProps | undefined): SerializableProps;
30
+ /**
31
+ * Renders a non-React layout or HTML template and enforces that mixed shells
32
+ * return serialized HTML.
33
+ */
34
+ export declare function renderNonReactShellComponent<P extends SerializableProps>(Component: (props: P) => EcoPagesElement | Promise<EcoPagesElement>, props: P, label: 'Layout' | 'HtmlTemplate' | 'Component'): Promise<string>;
35
+ /**
36
+ * Renders one React component while preserving already-resolved child HTML.
37
+ *
38
+ * @remarks
39
+ * When nested foreign-subtree resolution has already produced child HTML, the child
40
+ * payload must remain raw SSR output rather than a React string child, otherwise
41
+ * React would escape it. This helper renders a unique token through React and swaps
42
+ * that token back to the resolved HTML afterward.
43
+ */
44
+ export declare function renderComponentHtml(options: {
45
+ input: ComponentRenderInput;
46
+ context: ReactComponentRenderContext;
47
+ runtimeContext?: ReactForeignSubtreeResolutionContext;
48
+ runtime: ReactRuntimeModules;
49
+ }): string;
50
+ export declare function toReactNode(children: unknown, integrationName: string): ReactNode;
51
+ /**
52
+ * Restores raw child HTML placeholders stored on the foreign-subtree runtime context.
53
+ *
54
+ * @remarks
55
+ * Queued foreign-subtree resolution may render children through a fragment path before
56
+ * nested integration tokens are resolved. React must never see resolved child HTML as a
57
+ * normal string child or it would escape it.
58
+ */
59
+ export declare function restoreRuntimeChildHtml(html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined): string;
@@ -0,0 +1,76 @@
1
+ /**
2
+ * React component SSR helpers: renderToString, foreign-subtree HTML, island attributes.
3
+ */
4
+ import { isValidElement } from 'react';
5
+ import { asReactComponent } from './component-ownership.js';
6
+ import { ReactRenderError } from './errors.js';
7
+ export function buildHydrationProps(props) {
8
+ if (!props || !Object.prototype.hasOwnProperty.call(props, 'locals')) {
9
+ return props ?? {};
10
+ }
11
+ const { locals: _locals, ...hydrationProps } = props;
12
+ return hydrationProps;
13
+ }
14
+ /**
15
+ * Renders a non-React layout or HTML template and enforces that mixed shells
16
+ * return serialized HTML.
17
+ */
18
+ export async function renderNonReactShellComponent(Component, props, label) {
19
+ const output = await Component(props);
20
+ if (typeof output === 'string') {
21
+ return output;
22
+ }
23
+ throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
24
+ }
25
+ /**
26
+ * Renders one React component while preserving already-resolved child HTML.
27
+ *
28
+ * @remarks
29
+ * When nested foreign-subtree resolution has already produced child HTML, the child
30
+ * payload must remain raw SSR output rather than a React string child, otherwise
31
+ * React would escape it. This helper renders a unique token through React and swaps
32
+ * that token back to the resolved HTML afterward.
33
+ */
34
+ export function renderComponentHtml(options) {
35
+ const { input, context, runtimeContext, runtime } = options;
36
+ const { react, reactDomServer } = runtime;
37
+ if (input.children === undefined) {
38
+ return reactDomServer.renderToString(react.createElement(asReactComponent(input.component), input.props));
39
+ }
40
+ if (isValidElement(input.children)) {
41
+ return reactDomServer.renderToString(react.createElement(asReactComponent(input.component), input.props, input.children));
42
+ }
43
+ const resolvedChildHtml = typeof input.children === 'string' ? input.children : String(input.children ?? '');
44
+ const rawChildrenToken = `__ECO_RAW_HTML_CHILD_${context.componentInstanceId ?? 'component'}__`;
45
+ if (runtimeContext) {
46
+ runtimeContext.rawChildrenToken = rawChildrenToken;
47
+ runtimeContext.rawChildrenHtml = resolvedChildHtml;
48
+ }
49
+ const html = reactDomServer.renderToString(react.createElement(asReactComponent(input.component), input.props, rawChildrenToken));
50
+ return html.split(rawChildrenToken).join(resolvedChildHtml);
51
+ }
52
+ export function toReactNode(children, integrationName) {
53
+ if (children === null ||
54
+ typeof children === 'string' ||
55
+ typeof children === 'number' ||
56
+ typeof children === 'boolean' ||
57
+ isValidElement(children) ||
58
+ Array.isArray(children)) {
59
+ return children;
60
+ }
61
+ throw new TypeError(`[ecopages] ${integrationName} renderer expected a React node child.`);
62
+ }
63
+ /**
64
+ * Restores raw child HTML placeholders stored on the foreign-subtree runtime context.
65
+ *
66
+ * @remarks
67
+ * Queued foreign-subtree resolution may render children through a fragment path before
68
+ * nested integration tokens are resolved. React must never see resolved child HTML as a
69
+ * normal string child or it would escape it.
70
+ */
71
+ export function restoreRuntimeChildHtml(html, runtimeContext) {
72
+ if (!runtimeContext?.rawChildrenToken || runtimeContext.rawChildrenHtml === undefined) {
73
+ return html;
74
+ }
75
+ return html.split(runtimeContext.rawChildrenToken).join(runtimeContext.rawChildrenHtml);
76
+ }
@@ -0,0 +1,9 @@
1
+ /** @jsxImportSource react */
2
+ import { eco } from '@ecopages/core';
3
+ /**
4
+ * Renders a foreign or same-integration eco component from a React JSX file
5
+ * without forcing inline mixed-JSX authoring.
6
+ */
7
+ export function EcoEmbed({ component, props, children, }) {
8
+ return eco.embed(component, props, children);
9
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Errors thrown by the React integration renderer and bundling paths.
3
+ */
4
+ /**
5
+ * Error thrown when an error occurs while rendering a React component.
6
+ */
7
+ export declare class ReactRenderError extends Error {
8
+ constructor(message: string);
9
+ }
10
+ /**
11
+ * Error thrown when an error occurs while bundling a React component.
12
+ */
13
+ export declare class BundleError extends Error {
14
+ readonly logs: string[];
15
+ constructor(message: string, logs: string[]);
16
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Errors thrown by the React integration renderer and bundling paths.
3
+ */
4
+ /**
5
+ * Error thrown when an error occurs while rendering a React component.
6
+ */
7
+ export class ReactRenderError extends Error {
8
+ constructor(message) {
9
+ super(message);
10
+ this.name = 'ReactRenderError';
11
+ }
12
+ }
13
+ /**
14
+ * Error thrown when an error occurs while bundling a React component.
15
+ */
16
+ export class BundleError extends Error {
17
+ logs;
18
+ constructor(message, logs) {
19
+ super(message);
20
+ this.name = 'BundleError';
21
+ this.logs = logs;
22
+ }
23
+ }
@@ -0,0 +1,59 @@
1
+ const VOID_TAGS = new Set([
2
+ 'area',
3
+ 'base',
4
+ 'br',
5
+ 'col',
6
+ 'embed',
7
+ 'hr',
8
+ 'img',
9
+ 'input',
10
+ 'link',
11
+ 'meta',
12
+ 'param',
13
+ 'source',
14
+ 'track',
15
+ 'wbr',
16
+ ]);
17
+ /**
18
+ * Returns true when HTML contains exactly one root element node.
19
+ *
20
+ * Used by component-level React rendering to decide whether root attributes can
21
+ * be attached safely without introducing synthetic wrapper nodes.
22
+ */
23
+ export function hasSingleRootElement(html) {
24
+ const firstTagMatch = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/);
25
+ if (!firstTagMatch) {
26
+ return false;
27
+ }
28
+ const firstTag = firstTagMatch[1].toLowerCase();
29
+ const firstTagText = firstTagMatch[0];
30
+ const firstTagStart = firstTagMatch.index ?? 0;
31
+ const firstTagEnd = firstTagStart + firstTagText.length;
32
+ const isSelfClosing = /\/\s*>$/.test(firstTagText);
33
+ if (isSelfClosing || VOID_TAGS.has(firstTag)) {
34
+ return html.slice(firstTagEnd).trim().length === 0;
35
+ }
36
+ const tokenRegex = /<\/?([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/g;
37
+ tokenRegex.lastIndex = firstTagEnd;
38
+ let depth = 1;
39
+ for (let token = tokenRegex.exec(html); token; token = tokenRegex.exec(html)) {
40
+ const tagText = token[0];
41
+ const tagName = token[1].toLowerCase();
42
+ const isClosing = tagText.startsWith('</');
43
+ const tokenSelfClosing = /\/\s*>$/.test(tagText);
44
+ if (VOID_TAGS.has(tagName) || tokenSelfClosing) {
45
+ continue;
46
+ }
47
+ if (isClosing) {
48
+ depth--;
49
+ if (depth === 0) {
50
+ const afterRoot = html.slice(token.index + token[0].length).trim();
51
+ return afterRoot.length === 0;
52
+ }
53
+ }
54
+ else {
55
+ depth++;
56
+ }
57
+ }
58
+ return false;
59
+ }
@@ -0,0 +1,66 @@
1
+ import * as bundledReact from 'react';
2
+ import type { FunctionComponent, ReactElement } from 'react';
3
+ import type { EcoComponent, EcoPageLayoutEntry, LayoutPropsContext } from '@ecopages/core';
4
+ import type { EcoComponentConfig } from '@ecopages/core';
5
+ export type LayoutComposeContext = LayoutPropsContext;
6
+ export type ReactRuntime = typeof bundledReact;
7
+ export type LayoutComposeOptions = {
8
+ context?: LayoutComposeContext;
9
+ /** @remarks Pass the app-resolved React runtime during SSR so composition matches `renderToString`. */
10
+ react?: ReactRuntime;
11
+ /**
12
+ * Optional resolver that substitutes cached layout instances and React keys
13
+ * for SPA layout persistence.
14
+ */
15
+ resolvePersistedTier?: (layout: EcoComponent, index: number) => {
16
+ layout: EcoComponent;
17
+ key?: string;
18
+ };
19
+ };
20
+ export type LayoutShellEntry = {
21
+ component: EcoComponent;
22
+ props?: Record<string, unknown>;
23
+ };
24
+ export type ComposablePage<P extends Record<string, unknown> = Record<string, unknown>> = FunctionComponent<P> & {
25
+ config?: Pick<EcoComponentConfig, 'layouts' | 'layoutEntries'>;
26
+ };
27
+ /**
28
+ * Reads request-scoped layout context from serialized page props.
29
+ */
30
+ export declare function resolveLayoutContext(pageProps: Record<string, unknown>): LayoutComposeContext;
31
+ /**
32
+ * Builds layout prop factory context from document-shell layout entries.
33
+ *
34
+ * @remarks
35
+ * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
36
+ */
37
+ export declare function resolveLayoutContextFromShell(pageProps: Record<string, unknown>, shellLayouts: LayoutShellEntry[]): LayoutComposeContext;
38
+ /**
39
+ * Resolves props for one layout entry, merging shell locals with an optional factory.
40
+ */
41
+ export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutComposeContext): Record<string, unknown>;
42
+ /**
43
+ * @remarks
44
+ * Eco page components are wider than React layout composition input; runtime checks narrow callables.
45
+ */
46
+ export declare function assertComposablePage(Page: unknown): ComposablePage;
47
+ /**
48
+ * Builds the client or SSR React tree for a page and its outer→inner layout stack.
49
+ *
50
+ * @remarks
51
+ * Layout prop factories receive `LayoutPropsContext`. For SSR, pass `options.react` from the
52
+ * app-resolved runtime. Client code can omit it and use the bundled React import.
53
+ */
54
+ export declare function composeLayoutPageTree<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, options?: LayoutComposeOptions): ReactElement;
55
+ /**
56
+ * Builds a layout tree from explicit document-shell layout entries.
57
+ *
58
+ * @remarks
59
+ * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
60
+ * Shell `entry.props` are authoritative; page config normalization is not required.
61
+ */
62
+ export declare function composeLayoutPageTreeFromShell<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, shellLayouts: LayoutShellEntry[], options?: LayoutComposeOptions): ReactElement;
63
+ /**
64
+ * Normalizes page config layout metadata to an outer→inner component list.
65
+ */
66
+ export declare function normalizePageLayoutComponents(layouts?: EcoComponent[]): EcoComponent[];
@@ -0,0 +1,134 @@
1
+ import * as bundledReact from 'react';
2
+ function resolveReact(options) {
3
+ return options?.react ?? bundledReact;
4
+ }
5
+ /**
6
+ * @remarks
7
+ * Eco components are wider than React's `createElement` input; runtime checks narrow callables.
8
+ */
9
+ function toReactComponent(component) {
10
+ if (typeof component !== 'function') {
11
+ throw new TypeError('[ecopages] Expected a function component for layout composition.');
12
+ }
13
+ return component;
14
+ }
15
+ /**
16
+ * Reads request-scoped layout context from serialized page props.
17
+ */
18
+ export function resolveLayoutContext(pageProps) {
19
+ const context = {};
20
+ if (pageProps.params !== undefined) {
21
+ context.params = pageProps.params;
22
+ }
23
+ if (pageProps.query !== undefined) {
24
+ context.query = pageProps.query;
25
+ }
26
+ if (pageProps.locals !== undefined) {
27
+ context.locals = pageProps.locals;
28
+ }
29
+ return context;
30
+ }
31
+ /**
32
+ * Builds layout prop factory context from document-shell layout entries.
33
+ *
34
+ * @remarks
35
+ * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
36
+ */
37
+ export function resolveLayoutContextFromShell(pageProps, shellLayouts) {
38
+ const context = {};
39
+ if (pageProps.params !== undefined) {
40
+ context.params = pageProps.params;
41
+ }
42
+ if (pageProps.query !== undefined) {
43
+ context.query = pageProps.query;
44
+ }
45
+ for (const entry of shellLayouts) {
46
+ if (entry.props !== undefined && Object.prototype.hasOwnProperty.call(entry.props, 'locals')) {
47
+ context.locals = entry.props.locals;
48
+ break;
49
+ }
50
+ }
51
+ return context;
52
+ }
53
+ /**
54
+ * Resolves props for one layout entry, merging shell locals with an optional factory.
55
+ */
56
+ export function resolveLayoutEntryProps(entry, context) {
57
+ const shellProps = context.locals ? { locals: context.locals } : {};
58
+ if (!entry.props) {
59
+ return shellProps;
60
+ }
61
+ return {
62
+ ...shellProps,
63
+ ...entry.props(context),
64
+ };
65
+ }
66
+ /**
67
+ * @remarks
68
+ * Eco page components are wider than React layout composition input; runtime checks narrow callables.
69
+ */
70
+ export function assertComposablePage(Page) {
71
+ if (typeof Page !== 'function') {
72
+ throw new TypeError('[ecopages] Expected a function page component for layout composition.');
73
+ }
74
+ return Page;
75
+ }
76
+ /**
77
+ * Builds the client or SSR React tree for a page and its outer→inner layout stack.
78
+ *
79
+ * @remarks
80
+ * Layout prop factories receive `LayoutPropsContext`. For SSR, pass `options.react` from the
81
+ * app-resolved runtime. Client code can omit it and use the bundled React import.
82
+ */
83
+ export function composeLayoutPageTree(Page, pageProps, options) {
84
+ const { createElement } = resolveReact(options);
85
+ const context = options?.context ?? resolveLayoutContext(pageProps);
86
+ const pageElement = createElement(Page, pageProps);
87
+ const layoutEntries = Page.config?.layoutEntries;
88
+ const resolvePersistedTier = options?.resolvePersistedTier;
89
+ if (layoutEntries && layoutEntries.length > 0) {
90
+ return [...layoutEntries].reverse().reduce((children, entry, reverseIndex) => {
91
+ const index = layoutEntries.length - 1 - reverseIndex;
92
+ const layoutProps = resolveLayoutEntryProps(entry, context);
93
+ const tier = resolvePersistedTier?.(entry.component, index);
94
+ const Layout = toReactComponent(tier?.layout ?? entry.component);
95
+ const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
96
+ return createElement(Layout, elementProps, children);
97
+ }, pageElement);
98
+ }
99
+ const layouts = Page.config?.layouts;
100
+ if (layouts && layouts.length > 0) {
101
+ const layoutProps = context.locals ? { locals: context.locals } : {};
102
+ return [...layouts].reverse().reduce((children, Layout, reverseIndex) => {
103
+ const index = layouts.length - 1 - reverseIndex;
104
+ const tier = resolvePersistedTier?.(Layout, index);
105
+ const ResolvedLayout = toReactComponent(tier?.layout ?? Layout);
106
+ const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
107
+ return createElement(ResolvedLayout, elementProps, children);
108
+ }, pageElement);
109
+ }
110
+ return pageElement;
111
+ }
112
+ /**
113
+ * Builds a layout tree from explicit document-shell layout entries.
114
+ *
115
+ * @remarks
116
+ * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
117
+ * Shell `entry.props` are authoritative; page config normalization is not required.
118
+ */
119
+ export function composeLayoutPageTreeFromShell(Page, pageProps, shellLayouts, options) {
120
+ const { createElement } = resolveReact(options);
121
+ if (shellLayouts.length === 0) {
122
+ return composeLayoutPageTree(Page, pageProps, options);
123
+ }
124
+ const pageElement = createElement(Page, pageProps);
125
+ return [...shellLayouts].reverse().reduce((children, entry) => {
126
+ return createElement(toReactComponent(entry.component), entry.props ?? {}, children);
127
+ }, pageElement);
128
+ }
129
+ /**
130
+ * Normalizes page config layout metadata to an outer→inner component list.
131
+ */
132
+ export function normalizePageLayoutComponents(layouts) {
133
+ return layouts && layouts.length > 0 ? layouts : [];
134
+ }