@ecopages/react 0.2.0-beta.25 → 0.2.0-beta.27

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 (98) hide show
  1. package/README.md +17 -9
  2. package/package.json +42 -34
  3. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +7 -7
  4. package/src/{services/react-bundle.service.js → bundling/bundle.js} +9 -11
  5. package/src/{utils → bundling}/discover-layout-runtime-modules.js +2 -2
  6. package/src/{utils/react-runtime-alias-map.d.ts → bundling/runtime-alias-map.d.ts} +3 -3
  7. package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +5 -5
  8. package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +4 -4
  9. package/src/bundling/runtime-mode.d.ts +9 -0
  10. package/src/bundling/runtime-mode.js +6 -0
  11. package/src/{utils/client-graph-ast-transform.d.ts → client-graph/ast-transform.d.ts} +1 -1
  12. package/src/{utils/client-graph-ast-transform.js → client-graph/ast-transform.js} +1 -1
  13. package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
  14. package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
  15. package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +1 -1
  16. package/src/{utils/client-graph-boundary-plugin.js → client-graph/boundary-plugin.js} +3 -3
  17. package/src/{utils/client-graph-reachability.d.ts → client-graph/specifier-classification.d.ts} +1 -1
  18. package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +3 -6
  19. package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +11 -20
  20. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  21. package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
  22. package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
  23. package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +45 -52
  24. package/src/{utils → hydration}/hydration-scripts.d.ts +33 -41
  25. package/src/hydration/hydration-scripts.js +353 -0
  26. package/src/{utils → hydration}/hydration-scripts.test.browser.js +6 -4
  27. package/src/hydration/page-data-manifest.d.ts +58 -0
  28. package/src/hydration/page-data-manifest.js +53 -0
  29. package/src/hydration/page-data-reader.d.ts +31 -0
  30. package/src/hydration/page-data-reader.js +64 -0
  31. package/src/hydration/page-payload.d.ts +67 -0
  32. package/src/hydration/page-payload.js +104 -0
  33. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  34. package/src/hydration/serialize-page-data-script.js +31 -0
  35. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
  36. package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +3 -3
  37. package/src/{services/react-page-module.service.d.ts → page/page-module.d.ts} +4 -7
  38. package/src/{services/react-page-module.service.js → page/page-module.js} +5 -9
  39. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +7 -3
  40. package/src/{react.plugin.js → plugin/react.plugin.js} +32 -30
  41. package/src/{react.types.d.ts → plugin/react.types.d.ts} +23 -8
  42. package/src/render/component-ownership.d.ts +50 -0
  43. package/src/render/component-ownership.js +23 -0
  44. package/src/render/component-ssr.d.ts +113 -0
  45. package/src/render/component-ssr.js +202 -0
  46. package/src/render/errors.d.ts +16 -0
  47. package/src/render/errors.js +18 -0
  48. package/src/{layout-compose.d.ts → render/layout-compose.d.ts} +8 -0
  49. package/src/{layout-compose.js → render/layout-compose.js} +14 -6
  50. package/src/render/react-renderer.d.ts +137 -0
  51. package/src/render/react-renderer.js +444 -0
  52. package/src/render/react-runtime.d.ts +13 -0
  53. package/src/render/react-runtime.js +21 -0
  54. package/src/render/unified-layout-composition.d.ts +53 -0
  55. package/src/render/unified-layout-composition.js +89 -0
  56. package/src/react-renderer.d.ts +0 -254
  57. package/src/react-renderer.js +0 -726
  58. package/src/serialize-page-data-script.d.ts +0 -8
  59. package/src/serialize-page-data-script.js +0 -10
  60. package/src/services/pages-index.d.ts +0 -64
  61. package/src/services/pages-index.js +0 -73
  62. package/src/services/react-page-payload.service.d.ts +0 -46
  63. package/src/services/react-page-payload.service.js +0 -67
  64. package/src/utils/hydration-scripts.js +0 -371
  65. /package/src/{utils → app}/client-only.d.ts +0 -0
  66. /package/src/{utils → app}/client-only.js +0 -0
  67. /package/src/{utils → app}/dynamic.d.ts +0 -0
  68. /package/src/{utils → app}/dynamic.js +0 -0
  69. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  70. /package/src/{utils → app}/dynamic.test.browser.js +0 -0
  71. /package/src/{utils → bundling}/discover-layout-runtime-modules.d.ts +0 -0
  72. /package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +0 -0
  73. /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
  74. /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
  75. /package/src/{utils/react-plugin-runtime-modules.d.ts → bundling/runtime-modules.d.ts} +0 -0
  76. /package/src/{utils/react-plugin-runtime-modules.js → bundling/runtime-modules.js} +0 -0
  77. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  78. /package/src/{utils → client-graph}/component-config-traversal.js +0 -0
  79. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  80. /package/src/{utils → client-graph}/declared-modules.js +0 -0
  81. /package/src/{utils → client-graph}/reachability-analyzer.d.ts +0 -0
  82. /package/src/{utils → client-graph}/reachability-analyzer.js +0 -0
  83. /package/src/{utils/client-graph-reachability.js → client-graph/specifier-classification.js} +0 -0
  84. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  85. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  86. /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
  87. /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
  88. /package/src/{utils → hmr}/hmr-scripts.js +0 -0
  89. /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
  90. /package/src/{utils/react-mdx-loader-plugin.d.ts → mdx/mdx-loader-plugin.d.ts} +0 -0
  91. /package/src/{utils/react-mdx-loader-plugin.js → mdx/mdx-loader-plugin.js} +0 -0
  92. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  93. /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
  94. /package/src/{react.types.js → plugin/react.types.js} +0 -0
  95. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  96. /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
  97. /package/src/{utils → render}/html-boundary.d.ts +0 -0
  98. /package/src/{utils → render}/html-boundary.js +0 -0
@@ -0,0 +1,104 @@
1
+ import { LocalsAccessError } from "@ecopages/core/errors";
2
+ import {
3
+ serializePageDataManifestScript,
4
+ serializePageDataScript
5
+ } from "./serialize-page-data-script.js";
6
+ import { isReactManagedComponent } from "../render/component-ownership.js";
7
+ class PagePayloadService {
8
+ /**
9
+ * Resolves the browser-importable page module URL from processed page entry assets.
10
+ */
11
+ resolvePageModuleUrl(pagePackage, options) {
12
+ if (!options.routerEnabled) {
13
+ return void 0;
14
+ }
15
+ const entryScripts = pagePackage?.pageBrowserGraph?.entryAssets.filter(
16
+ (asset) => asset.kind === "script" && typeof asset.srcUrl === "string"
17
+ ) ?? [];
18
+ const bootstrapScript = entryScripts.find(
19
+ (asset) => asset.attributes?.["data-eco-page-bootstrap"] === "react-router"
20
+ );
21
+ return bootstrapScript?.srcUrl ?? entryScripts[0]?.srcUrl;
22
+ }
23
+ /**
24
+ * Creates the `__ECO_PAGE_DATA__` script for router hydration.
25
+ *
26
+ * @remarks
27
+ * When `moduleUrl` is present, emits the v1 envelope via
28
+ * {@link serializePageDataManifestScript}. Otherwise emits legacy flat props
29
+ * for non-router shells.
30
+ */
31
+ buildRouterPageDataScript(pageProps, moduleUrl) {
32
+ const props = { ...pageProps ?? {} };
33
+ if (moduleUrl) {
34
+ return serializePageDataManifestScript({ moduleUrl, props });
35
+ }
36
+ return serializePageDataScript(props);
37
+ }
38
+ /**
39
+ * Builds shared document html contributions for router-backed React pages rendered
40
+ * through a non-React HTML shell.
41
+ */
42
+ buildNonReactDocumentContributions(options) {
43
+ if (isReactManagedComponent(options.htmlTemplate, options.reactIntegrationName) || !options.routerEnabled) {
44
+ return void 0;
45
+ }
46
+ return [
47
+ {
48
+ placement: "head-append",
49
+ html: this.buildRouterPageDataScript(options.pageProps, options.pageModuleUrl)
50
+ }
51
+ ];
52
+ }
53
+ /**
54
+ * Builds the browser-safe page-props object embedded into the final HTML.
55
+ *
56
+ * @remarks
57
+ * Narrower than the full server render input: only routing data, public page
58
+ * props, and explicitly allowed locals. Page module identity is threaded via
59
+ * `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
60
+ */
61
+ buildSerializedPageProps(options) {
62
+ return {
63
+ ...options.pageProps,
64
+ params: options.params,
65
+ query: options.query,
66
+ ...options.safeLocals && { locals: options.safeLocals }
67
+ };
68
+ }
69
+ /**
70
+ * Extracts the declared subset of locals for client-side hydration.
71
+ *
72
+ * @remarks
73
+ * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
74
+ * request-scoped data. Only keys declared via `Page.requires` are serialized.
75
+ * On static pages, `locals` is a Proxy that throws `LocalsAccessError`; this
76
+ * method returns `undefined` instead of throwing.
77
+ */
78
+ getSerializableLocals(locals, requiredLocals) {
79
+ try {
80
+ if (!locals) {
81
+ return void 0;
82
+ }
83
+ const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
84
+ if (requiredKeys.length === 0) {
85
+ return void 0;
86
+ }
87
+ const serializedLocals = Object.fromEntries(
88
+ requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
89
+ );
90
+ if (Object.keys(serializedLocals).length > 0) {
91
+ return serializedLocals;
92
+ }
93
+ return void 0;
94
+ } catch (error) {
95
+ if (error instanceof LocalsAccessError) {
96
+ return void 0;
97
+ }
98
+ throw error;
99
+ }
100
+ }
101
+ }
102
+ export {
103
+ PagePayloadService
104
+ };
@@ -0,0 +1,27 @@
1
+ import { type EcoPageDataDocumentPayload, type EcoPageDataProps } from './page-data-manifest.js';
2
+ export { ECO_PAGE_DATA_SCHEMA_VERSION, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolvePageDataDocumentPayload, type EcoPageDataDocumentPayload, type EcoPageDataManifestV1, type EcoPageDataProps, } from './page-data-manifest.js';
3
+ /**
4
+ * Escapes page data JSON for safe embedding in HTML script bodies.
5
+ */
6
+ export declare function escapePageDataJson(pageProps: EcoPageDataDocumentPayload | undefined): string;
7
+ /**
8
+ * Emits the canonical `__ECO_PAGE_DATA__` bootstrap script tag.
9
+ *
10
+ * @remarks
11
+ * Accepts a v1 envelope or legacy flat props. Router-enabled documents should
12
+ * use {@link serializePageDataManifestScript} so clients can discover the page
13
+ * module without parsing hydration JavaScript.
14
+ */
15
+ export declare function serializePageDataScript(pageProps: EcoPageDataDocumentPayload | undefined): string;
16
+ /**
17
+ * Emits a versioned page-data envelope for React router documents.
18
+ *
19
+ * @remarks
20
+ * Canonical HTML serializer for router-enabled pages. SPA commit paths that
21
+ * build a React element instead of an HTML string use
22
+ * {@link resolvePageDataDocumentPayload} with the same envelope shape.
23
+ */
24
+ export declare function serializePageDataManifestScript(input: {
25
+ moduleUrl: string;
26
+ props: EcoPageDataProps;
27
+ }): string;
@@ -0,0 +1,31 @@
1
+ import {
2
+ createEcoPageDataManifestV1
3
+ } from "./page-data-manifest.js";
4
+ import {
5
+ ECO_PAGE_DATA_SCHEMA_VERSION,
6
+ createEcoPageDataManifestV1 as createEcoPageDataManifestV12,
7
+ isEcoPageDataManifestV1,
8
+ resolveEcoPageDataModuleUrl,
9
+ resolveEcoPageDataProps,
10
+ resolvePageDataDocumentPayload
11
+ } from "./page-data-manifest.js";
12
+ function escapePageDataJson(pageProps) {
13
+ return JSON.stringify(pageProps ?? {}).replace(/</g, "\\u003c");
14
+ }
15
+ function serializePageDataScript(pageProps) {
16
+ return `<script id="__ECO_PAGE_DATA__" type="application/json">${escapePageDataJson(pageProps)}<\/script>`;
17
+ }
18
+ function serializePageDataManifestScript(input) {
19
+ return serializePageDataScript(createEcoPageDataManifestV1(input));
20
+ }
21
+ export {
22
+ ECO_PAGE_DATA_SCHEMA_VERSION,
23
+ createEcoPageDataManifestV12 as createEcoPageDataManifestV1,
24
+ escapePageDataJson,
25
+ isEcoPageDataManifestV1,
26
+ resolveEcoPageDataModuleUrl,
27
+ resolveEcoPageDataProps,
28
+ resolvePageDataDocumentPayload,
29
+ serializePageDataManifestScript,
30
+ serializePageDataScript
31
+ };
@@ -1,10 +1,10 @@
1
1
  import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
2
2
  import { type AssetProcessingService, type ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
3
- import type { ReactPageModuleService } from './react-page-module.service.js';
3
+ import type { PageModuleService } from '../page/page-module.js';
4
4
  type MdxConfigDependencyProcessor = (components: Partial<EcoComponent>[]) => Promise<ProcessedAsset[]>;
5
- export interface ReactMdxConfigDependencyServiceConfig {
5
+ export interface MdxConfigDependencyServiceConfig {
6
6
  integrationName: string;
7
- pageModuleService: Pick<ReactPageModuleService, 'ensureConfigFileMetadata'>;
7
+ pageModuleService: Pick<PageModuleService, 'ensureConfigFileMetadata'>;
8
8
  assetProcessingService?: Pick<AssetProcessingService, 'processDependencies'>;
9
9
  }
10
10
  /**
@@ -15,9 +15,9 @@ export interface ReactMdxConfigDependencyServiceConfig {
15
15
  * component configs so the shared dependency pipeline can process them without
16
16
  * growing more MDX-specific logic inside the renderer.
17
17
  */
18
- export declare class ReactMdxConfigDependencyService {
18
+ export declare class MdxConfigDependencyService {
19
19
  private readonly config;
20
- constructor(config: ReactMdxConfigDependencyServiceConfig);
20
+ constructor(config: MdxConfigDependencyServiceConfig);
21
21
  /**
22
22
  * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
23
23
  */
@@ -3,8 +3,8 @@ import { rapidhash } from "@ecopages/core/hash";
3
3
  import {
4
4
  AssetFactory
5
5
  } from "@ecopages/core/services/asset-processing-service";
6
- import { collectFromConfigForest, getComponentConfigs } from "../utils/component-config-traversal.js";
7
- class ReactMdxConfigDependencyService {
6
+ import { collectFromConfigForest, getComponentConfigs } from "../client-graph/component-config-traversal.js";
7
+ class MdxConfigDependencyService {
8
8
  config;
9
9
  constructor(config) {
10
10
  this.config = config;
@@ -116,5 +116,5 @@ class ReactMdxConfigDependencyService {
116
116
  }
117
117
  }
118
118
  export {
119
- ReactMdxConfigDependencyService
119
+ MdxConfigDependencyService
120
120
  };
@@ -9,12 +9,9 @@
9
9
  */
10
10
  import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
11
11
  /**
12
- * Configuration for the ReactPageModuleService.
12
+ * Configuration for the PageModuleService.
13
13
  */
14
- export interface ReactPageModuleServiceConfig {
15
- rootDir: string;
16
- distDir: string;
17
- workDir: string;
14
+ export interface PageModuleServiceConfig {
18
15
  layoutsDir?: string;
19
16
  componentsDir?: string;
20
17
  mdxExtensions: string[];
@@ -24,9 +21,9 @@ export interface ReactPageModuleServiceConfig {
24
21
  /**
25
22
  * Manages page module metadata resolution and hydration analysis for React pages.
26
23
  */
27
- export declare class ReactPageModuleService {
24
+ export declare class PageModuleService {
28
25
  private readonly config;
29
- constructor(config: ReactPageModuleServiceConfig);
26
+ constructor(config: PageModuleServiceConfig);
30
27
  /**
31
28
  * Checks if the given file path corresponds to an MDX file based on configured extensions.
32
29
  */
@@ -1,9 +1,9 @@
1
1
  import path from "node:path";
2
2
  import { rapidhash } from "@ecopages/core/hash";
3
3
  import { fileSystem } from "@ecopages/file-system";
4
- import { someInConfigTree } from "../utils/component-config-traversal.js";
5
- import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
6
- class ReactPageModuleService {
4
+ import { someInConfigTree } from "../client-graph/component-config-traversal.js";
5
+ import { collectPageDeclaredModulesFromModule } from "../client-graph/declared-modules.js";
6
+ class PageModuleService {
7
7
  config;
8
8
  constructor(config) {
9
9
  this.config = config;
@@ -64,13 +64,9 @@ class ReactPageModuleService {
64
64
  return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
65
65
  }
66
66
  collectPageDeclaredModules(pageModule) {
67
- const declarations = [
68
- ...collectDeclaredModulesInConfig(pageModule.default?.config),
69
- ...collectDeclaredModulesInConfig(pageModule.config)
70
- ];
71
- return Array.from(new Set(declarations));
67
+ return collectPageDeclaredModulesFromModule(pageModule);
72
68
  }
73
69
  }
74
70
  export {
75
- ReactPageModuleService
71
+ PageModuleService
76
72
  };
@@ -2,7 +2,7 @@ import { IntegrationPlugin, type EcoBuildPlugin } from '@ecopages/core/plugins/i
2
2
  import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
3
3
  import type { HmrStrategy } from '@ecopages/core/hmr/hmr-strategy';
4
4
  import type React from 'react';
5
- import { ReactRenderer } from './react-renderer.js';
5
+ import { ReactRenderer } from '../render/react-renderer.js';
6
6
  import type { ReactPluginOptions } from './react.types.js';
7
7
  export type { ReactMdxOptions, ReactPluginOptions, ReactRendererConfig } from './react.types.js';
8
8
  /**
@@ -23,11 +23,15 @@ export declare class ReactPlugin extends IntegrationPlugin<React.ReactNode> {
23
23
  private readonly runtimeBundleService;
24
24
  private readonly hmrPageMetadataCache;
25
25
  private readonly clientGraphBoundaryCache;
26
+ private hmrStrategy?;
26
27
  private runtimeDependenciesInitialized;
27
28
  /**
28
- * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
29
+ * When true, always emit page browser graph / hydration assets.
30
+ *
31
+ * @remarks
32
+ * Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
29
33
  */
30
- private readonly explicitGraphEnabled;
34
+ private readonly forceBrowserGraph;
31
35
  private readonly rendererConfig;
32
36
  constructor(options?: ReactPluginOptions);
33
37
  /**
@@ -4,18 +4,15 @@ import {
4
4
  import { Logger } from "@ecopages/logger";
5
5
  import path from "node:path";
6
6
  import { REACT_PLUGIN_NAME } from "./react.constants.js";
7
- import { ReactRenderer } from "./react-renderer.js";
8
- import { ReactHmrStrategy } from "./react-hmr-strategy.js";
9
- import { ReactRuntimeBundleService } from "./services/react-runtime-bundle.service.js";
10
- import { ReactHmrPageMetadataCache } from "./services/react-hmr-page-metadata-cache.js";
11
- import { createReactMdxLoaderPlugin } from "./utils/react-mdx-loader-plugin.js";
7
+ import { ReactRenderer } from "../render/react-renderer.js";
8
+ import { ReactHmrStrategy } from "../hmr/hmr-strategy.js";
9
+ import { RuntimeBundleService } from "../bundling/runtime-bundle.js";
10
+ import { HmrPageMetadataCache } from "../hmr/page-metadata-cache.js";
11
+ import { createReactMdxLoaderPlugin } from "../mdx/mdx-loader-plugin.js";
12
12
  import { appendMdxExtensions, resolveMdxCompilerOptions } from "@ecopages/mdx/core";
13
- import { ClientGraphBoundaryCache } from "./utils/client-graph-boundary-cache.js";
14
- import { discoverLayoutRuntimeModuleSpecifiers } from "./utils/discover-layout-runtime-modules.js";
15
- import {
16
- mergeReactPluginRuntimeModules,
17
- resolveReactPluginRuntimeModules
18
- } from "./utils/react-plugin-runtime-modules.js";
13
+ import { ClientGraphBoundaryCache } from "../client-graph/boundary-cache.js";
14
+ import { discoverLayoutRuntimeModuleSpecifiers } from "../bundling/discover-layout-runtime-modules.js";
15
+ import { mergeReactPluginRuntimeModules, resolveReactPluginRuntimeModules } from "../bundling/runtime-modules.js";
19
16
  const appLogger = new Logger("[ReactPlugin]");
20
17
  const PLUGIN_NAME = REACT_PLUGIN_NAME;
21
18
  const resolveReactMdxCompilerOptions = (mdxOptions) => resolveMdxCompilerOptions(mdxOptions, { jsxImportSource: "react" });
@@ -45,8 +42,8 @@ const resolveReactPluginOptions = (options) => {
45
42
  runtimeModules: resolvedRuntimeModules,
46
43
  mdxCompilerOptions: mdxEnabled && mdx ? resolveReactMdxCompilerOptions(mdx) : void 0,
47
44
  mdxExtensions,
48
- hmrPageMetadataCache: new ReactHmrPageMetadataCache(),
49
- explicitGraphEnabled: explicitGraph ?? false
45
+ hmrPageMetadataCache: new HmrPageMetadataCache(),
46
+ forceBrowserGraph: explicitGraph ?? false
50
47
  };
51
48
  return {
52
49
  ...baseConfig,
@@ -65,11 +62,15 @@ class ReactPlugin extends IntegrationPlugin {
65
62
  runtimeBundleService;
66
63
  hmrPageMetadataCache;
67
64
  clientGraphBoundaryCache;
65
+ hmrStrategy;
68
66
  runtimeDependenciesInitialized = false;
69
67
  /**
70
- * Indicates whether React explicit graph mode is enabled for renderer/HMR behavior.
68
+ * When true, always emit page browser graph / hydration assets.
69
+ *
70
+ * @remarks
71
+ * Mapped from public `explicitGraph`. Does not skip client-graph AST stripping.
71
72
  */
72
- explicitGraphEnabled;
73
+ forceBrowserGraph;
73
74
  rendererConfig;
74
75
  constructor(options) {
75
76
  const config = resolveReactPluginOptions(options);
@@ -85,19 +86,19 @@ class ReactPlugin extends IntegrationPlugin {
85
86
  this.mdxCompilerOptions = rendererConfig.mdxCompilerOptions;
86
87
  this.mdxEnabled = Boolean(rendererConfig.mdxCompilerOptions);
87
88
  this.mdxExtensions = rendererConfig.mdxExtensions ?? [".mdx"];
88
- this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new ReactHmrPageMetadataCache();
89
+ this.hmrPageMetadataCache = rendererConfig.hmrPageMetadataCache ?? new HmrPageMetadataCache();
89
90
  this.clientGraphBoundaryCache = new ClientGraphBoundaryCache();
90
- this.explicitGraphEnabled = rendererConfig.explicitGraphEnabled ?? false;
91
+ this.forceBrowserGraph = rendererConfig.forceBrowserGraph ?? false;
91
92
  this.rendererConfig = {
92
93
  ...rendererConfig,
93
94
  mdxExtensions: this.mdxExtensions,
94
95
  hmrPageMetadataCache: this.hmrPageMetadataCache,
95
- explicitGraphEnabled: this.explicitGraphEnabled
96
+ forceBrowserGraph: this.forceBrowserGraph
96
97
  };
97
98
  if (this.mdxEnabled) {
98
99
  appLogger.debug("MDX mode enabled with React jsx runtime");
99
100
  }
100
- this.runtimeBundleService = new ReactRuntimeBundleService({
101
+ this.runtimeBundleService = new RuntimeBundleService({
101
102
  routerAdapter: this.routerAdapter,
102
103
  runtimeModules: this.rendererConfig.runtimeModules
103
104
  });
@@ -204,17 +205,18 @@ class ReactPlugin extends IntegrationPlugin {
204
205
  if (!this.hmrManager || !this.appConfig) {
205
206
  return void 0;
206
207
  }
207
- const context = this.hmrManager.getDefaultContext();
208
- return new ReactHmrStrategy({
209
- context,
210
- pageMetadataCache: this.hmrPageMetadataCache,
211
- runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
212
- mdxCompilerOptions: this.mdxCompilerOptions,
213
- ownedTemplateExtensions: this.extensions,
214
- allTemplateExtensions: this.appConfig.templatesExt,
215
- explicitGraphEnabled: this.explicitGraphEnabled,
216
- clientGraphBoundaryCache: this.clientGraphBoundaryCache
217
- });
208
+ if (!this.hmrStrategy) {
209
+ this.hmrStrategy = new ReactHmrStrategy({
210
+ context: this.hmrManager.getDefaultContext(),
211
+ pageMetadataCache: this.hmrPageMetadataCache,
212
+ runtimeManifest: this.runtimeBundleService.getRuntimeManifest("development"),
213
+ mdxCompilerOptions: this.mdxCompilerOptions,
214
+ ownedTemplateExtensions: this.extensions,
215
+ allTemplateExtensions: this.appConfig.templatesExt,
216
+ clientGraphBoundaryCache: this.clientGraphBoundaryCache
217
+ });
218
+ }
219
+ return this.hmrStrategy;
218
220
  }
219
221
  }
220
222
  function reactPlugin(options) {
@@ -1,8 +1,8 @@
1
1
  import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
2
2
  import type { CompileOptions } from '@mdx-js/mdx';
3
- import type { ReactRouterAdapter } from './router-adapter.js';
4
- import type { ReactHmrPageMetadataCache } from './services/react-hmr-page-metadata-cache.js';
5
- import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from './utils/react-plugin-runtime-modules.js';
3
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
4
+ import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
5
+ import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from '../bundling/runtime-modules.js';
6
6
  /**
7
7
  * MDX configuration options for the React plugin.
8
8
  */
@@ -45,10 +45,18 @@ export type ReactPluginOptions = {
45
45
  extensions?: string[];
46
46
  dependencies?: AssetDefinition[];
47
47
  /**
48
- * Enables explicit client graph mode for React page entries.
48
+ * When true, always emit the page browser graph / hydration assets for React
49
+ * page entries, even when the page does not declare `dependencies.modules`
50
+ * and no router adapter is configured.
51
+ *
52
+ * @remarks
53
+ * This does not skip the client-graph AST boundary. Server-only
54
+ * `eco.page(...)` options such as `middleware` and `requires` are still
55
+ * stripped from browser bundles.
56
+ *
57
+ * With a router adapter, page hydration is already always enabled, so this
58
+ * option is redundant for SPA apps.
49
59
  *
50
- * When enabled, React page-entry bundling relies on explicit dependency declarations
51
- * and skips AST-based `middleware`/`requires` stripping in the React path.
52
60
  * @default false
53
61
  */
54
62
  explicitGraph?: boolean;
@@ -129,6 +137,13 @@ export type ReactRendererConfig = {
129
137
  runtimeModules?: ResolvedReactPluginRuntimeModule[];
130
138
  mdxCompilerOptions?: CompileOptions;
131
139
  mdxExtensions?: string[];
132
- hmrPageMetadataCache?: ReactHmrPageMetadataCache;
133
- explicitGraphEnabled?: boolean;
140
+ hmrPageMetadataCache?: HmrPageMetadataCache;
141
+ /**
142
+ * When true, always emit page browser graph / hydration assets for React pages.
143
+ *
144
+ * @remarks
145
+ * Mapped from the public `explicitGraph` plugin option. Does not skip the
146
+ * client-graph AST strip of server-only `eco.page(...)` options.
147
+ */
148
+ forceBrowserGraph?: boolean;
134
149
  };
@@ -0,0 +1,50 @@
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 injected
19
+ * `config.__eco.integration` metadata because pages can arrive through authored
20
+ * config as well as build-time component metadata.
21
+ */
22
+ export declare function getComponentIntegration(component?: {
23
+ config?: EcoComponentConfig;
24
+ } | null): string | undefined;
25
+ /**
26
+ * Returns whether a component should stay inside the React render lane.
27
+ *
28
+ * @remarks
29
+ * Components without explicit integration metadata are treated as React-owned
30
+ * because this renderer only receives them after the route pipeline has already
31
+ * selected the React integration.
32
+ */
33
+ export declare function isReactManagedComponent(component: {
34
+ config?: EcoComponentConfig;
35
+ } | null | undefined, reactIntegrationName: string): boolean;
36
+ export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
37
+ /**
38
+ * Commits a framework-agnostic component to React semantics.
39
+ *
40
+ * @remarks
41
+ * Core keeps `EcoComponent` broad so integrations can share the same public surface;
42
+ * once the React renderer is executing, `createElement()` needs a concrete React
43
+ * component signature.
44
+ */
45
+ export declare function asReactComponent<P extends SerializableProps>(component: unknown): ReactRenderableComponent<P>;
46
+ /**
47
+ * Commits a mixed-shell component to the string-returning contract required by
48
+ * non-React layouts and HTML templates.
49
+ */
50
+ export declare function asNonReactShellComponent<P extends SerializableProps>(component: unknown): (props: P) => EcoPagesElement | Promise<EcoPagesElement>;
@@ -0,0 +1,23 @@
1
+ function getComponentIntegration(component) {
2
+ return component?.config?.integration ?? component?.config?.__eco?.integration;
3
+ }
4
+ function isReactManagedComponent(component, reactIntegrationName) {
5
+ const integration = getComponentIntegration(component);
6
+ return integration === void 0 || integration === reactIntegrationName;
7
+ }
8
+ function getComponentRequires(component) {
9
+ return component?.requires;
10
+ }
11
+ function asReactComponent(component) {
12
+ return component;
13
+ }
14
+ function asNonReactShellComponent(component) {
15
+ return component;
16
+ }
17
+ export {
18
+ asNonReactShellComponent,
19
+ asReactComponent,
20
+ getComponentIntegration,
21
+ getComponentRequires,
22
+ isReactManagedComponent
23
+ };
@@ -0,0 +1,113 @@
1
+ /**
2
+ * React component SSR helpers: renderToString, foreign-subtree HTML, island attributes.
3
+ */
4
+ import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement } from '@ecopages/core';
5
+ import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
6
+ import type { IntegrationRenderer } from '@ecopages/core/route-renderer/integration-renderer';
7
+ import type { ReactNode } from 'react';
8
+ import { type HydrationAssetService } from '../hydration/hydration-asset.js';
9
+ import { type SerializableProps } from './component-ownership.js';
10
+ import type { ReactRuntimeModules } from './react-runtime.js';
11
+ export type ReactComponentRenderContext = {
12
+ componentInstanceId?: string;
13
+ };
14
+ export type ReactForeignSubtreeResolutionContext = {
15
+ rendererCache: Map<string, IntegrationRenderer<any>>;
16
+ componentInstanceScope?: string;
17
+ nextForeignSubtreeId: number;
18
+ queuedResolutions: Array<{
19
+ token: string;
20
+ component: EcoComponent;
21
+ props: Record<string, unknown>;
22
+ componentInstanceId: string;
23
+ }>;
24
+ rawChildrenToken?: string;
25
+ rawChildrenHtml?: string;
26
+ };
27
+ export declare function buildHydrationProps(props: SerializableProps | undefined): SerializableProps;
28
+ /**
29
+ * Renders a non-React layout or HTML template and enforces that mixed shells
30
+ * return serialized HTML.
31
+ */
32
+ export declare function renderNonReactShellComponent<P extends SerializableProps>(Component: (props: P) => EcoPagesElement | Promise<EcoPagesElement>, props: P, label: 'Layout' | 'HtmlTemplate' | 'Component'): Promise<string>;
33
+ /**
34
+ * Renders one React component while preserving already-resolved child HTML.
35
+ *
36
+ * @remarks
37
+ * When nested foreign-subtree resolution has already produced child HTML, the child
38
+ * payload must remain raw SSR output rather than a React string child, otherwise
39
+ * React would escape it. This helper renders a unique token through React and swaps
40
+ * that token back to the resolved HTML afterward.
41
+ */
42
+ export declare function renderComponentHtml(options: {
43
+ input: ComponentRenderInput;
44
+ context: ReactComponentRenderContext;
45
+ runtimeContext?: ReactForeignSubtreeResolutionContext;
46
+ runtime: ReactRuntimeModules;
47
+ normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
48
+ }): string;
49
+ export declare function toReactNode(children: unknown, integrationName: string): ReactNode;
50
+ /**
51
+ * Restores raw child HTML placeholders stored on the foreign-subtree runtime context.
52
+ *
53
+ * @remarks
54
+ * Queued foreign-subtree resolution may render children through a fragment path before
55
+ * nested integration tokens are resolved. React must never see resolved child HTML as a
56
+ * normal string child or it would escape it.
57
+ */
58
+ export declare function restoreRuntimeChildHtml(html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined): string;
59
+ export declare function renderQueuedChildrenToHtml(options: {
60
+ children: unknown;
61
+ runtimeContext: ReactForeignSubtreeResolutionContext;
62
+ queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>;
63
+ resolveToken: (token: string) => Promise<string>;
64
+ runtime: ReactRuntimeModules;
65
+ integrationName: string;
66
+ normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
67
+ resolveQueuedTokens: (html: string, queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>, resolveToken: (token: string) => Promise<string>) => Promise<string>;
68
+ }): Promise<string | undefined>;
69
+ export declare function renderReactQueuedForeignSubtreeChildren(options: {
70
+ children: unknown;
71
+ currentRuntimeContext: ReactForeignSubtreeResolutionContext;
72
+ queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>;
73
+ resolveToken: (token: string) => Promise<string>;
74
+ runtime: ReactRuntimeModules;
75
+ integrationName: string;
76
+ normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
77
+ resolveQueuedTokens: (html: string, queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>, resolveToken: (token: string) => Promise<string>) => Promise<string>;
78
+ }): Promise<{
79
+ assets: ProcessedAsset[];
80
+ html?: string;
81
+ }>;
82
+ export declare function renderForeignComponentWithSerializedHtml(options: {
83
+ input: ComponentRenderInput;
84
+ runtimeContext: ReactForeignSubtreeResolutionContext | undefined;
85
+ integrationName: string;
86
+ canResolveAssets: boolean;
87
+ processComponentDependencies: (components: EcoComponent[]) => Promise<ProcessedAsset[]>;
88
+ dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
89
+ getRootTagName: (html: string) => string | undefined;
90
+ resolveQueuedForeignSubtreeHtml: (html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined) => Promise<{
91
+ assets: ProcessedAsset[];
92
+ html: string;
93
+ }>;
94
+ }): Promise<ComponentRenderResult>;
95
+ export declare function renderReactManagedComponent(options: {
96
+ input: ComponentRenderInput;
97
+ runtimeContext: ReactForeignSubtreeResolutionContext | undefined;
98
+ runtime: ReactRuntimeModules;
99
+ integrationName: string;
100
+ normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
101
+ resolveQueuedForeignSubtreeHtml: (html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined) => Promise<{
102
+ assets: ProcessedAsset[];
103
+ html: string;
104
+ }>;
105
+ getRootTagName: (html: string) => string | undefined;
106
+ dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
107
+ hydrationAssetService: HydrationAssetService;
108
+ canBuildIslandAssets: boolean;
109
+ }): Promise<ComponentRenderResult>;
110
+ export declare function createForeignSubtreeRuntimeContext(options: {
111
+ rendererCache: Map<string, IntegrationRenderer<any>>;
112
+ componentInstanceScope?: string;
113
+ }): ReactForeignSubtreeResolutionContext;