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

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
@@ -1,88 +0,0 @@
1
- import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
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
- /**
6
- * MDX configuration options for the React plugin.
7
- */
8
- export type ReactMdxOptions = {
9
- /**
10
- * Whether to enable MDX support.
11
- * @default false
12
- */
13
- enabled: boolean;
14
- /**
15
- * Compiler options for MDX.
16
- * @default undefined
17
- */
18
- compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
19
- /**
20
- * Remark plugins.
21
- * @default undefined
22
- */
23
- remarkPlugins?: CompileOptions['remarkPlugins'];
24
- /**
25
- * Rehype plugins.
26
- * @default undefined
27
- */
28
- rehypePlugins?: CompileOptions['rehypePlugins'];
29
- /**
30
- * Recma plugins.
31
- * @default undefined
32
- */
33
- recmaPlugins?: CompileOptions['recmaPlugins'];
34
- /**
35
- * Custom extensions to be treated as MDX files.
36
- * @default ['.mdx']
37
- */
38
- extensions?: string[];
39
- };
40
- /**
41
- * Options for the React plugin.
42
- */
43
- export type ReactPluginOptions = {
44
- extensions?: string[];
45
- dependencies?: AssetDefinition[];
46
- /**
47
- * Enables explicit client graph mode for React page entries.
48
- *
49
- * When enabled, React page-entry bundling relies on explicit dependency declarations
50
- * and skips AST-based `middleware`/`requires` stripping in the React path.
51
- * @default false
52
- */
53
- explicitGraph?: boolean;
54
- /**
55
- * Router adapter for SPA navigation.
56
- * When provided, pages with layouts will be wrapped in the router for client-side navigation.
57
- * @example
58
- * ```ts
59
- * import { ecoRouter } from '@ecopages/react-router';
60
- * reactPlugin({ router: ecoRouter() })
61
- * ```
62
- */
63
- router?: ReactRouterAdapter;
64
- /**
65
- * MDX configuration for handling .mdx files within the React plugin.
66
- * When enabled, MDX files are treated as React pages with full router support.
67
- * @example
68
- * ```ts
69
- * reactPlugin({
70
- * router: ecoRouter(),
71
- * mdx: {
72
- * enabled: true,
73
- * extensions: ['.mdx', '.md'],
74
- * remarkPlugins: [remarkGfm],
75
- * rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
76
- * }
77
- * })
78
- * ```
79
- */
80
- mdx?: ReactMdxOptions;
81
- };
82
- export type ReactRendererConfig = {
83
- routerAdapter?: ReactRouterAdapter;
84
- mdxCompilerOptions?: CompileOptions;
85
- mdxExtensions?: string[];
86
- hmrPageMetadataCache?: ReactHmrPageMetadataCache;
87
- explicitGraphEnabled?: boolean;
88
- };
@@ -1,64 +0,0 @@
1
- /**
2
- * Per-app index of React-owned page entrypoints.
3
- *
4
- * @remarks
5
- * The HMR strategy previously called `fileSystem.glob` on every
6
- * layout change. For apps with many pages this is wasteful: O(pages)
7
- * on every HMR event, and the result rarely changes between HMR
8
- * rebuilds.
9
- *
10
- * `PagesIndex` maintains a `Set` of owned page entrypoint paths. The
11
- * initial population is a single glob; subsequent mutations go through
12
- * `add` / `remove` (called by the HMR strategy when it observes a
13
- * file create/delete under `pagesDir`). The strategy reads via
14
- * `list()` for an O(1) snapshot of the current set.
15
- *
16
- * Phase 1 ships the class and the `list()` consumer. Watcher-driven
17
- * `add` / `remove` integration lands in a follow-up — for now the
18
- * strategy calls `refresh()` lazily, which is equivalent to the old
19
- * glob behavior but with a stable API for the future incremental
20
- * path.
21
- */
22
- export type PagesIndexOptions = {
23
- pagesDir: string;
24
- extensions?: string[];
25
- /**
26
- * Optional predicate to filter out non-page entrypoints (e.g.
27
- * test fixtures, generated files). Defaults to including every
28
- * file matching an extension.
29
- */
30
- isPageEntrypoint?: (absolutePath: string) => boolean;
31
- };
32
- export declare class PagesIndex {
33
- private readonly pagesDir;
34
- private readonly extensions;
35
- private readonly isPageEntrypoint;
36
- private readonly pages;
37
- private lastRefreshAt;
38
- constructor(options: PagesIndexOptions);
39
- /**
40
- * Rescan the pages directory and rebuild the index.
41
- *
42
- * Cheap to call multiple times in sequence (just a glob). The
43
- * real value of `PagesIndex` is the `add` / `remove` path that
44
- * callers can wire to the file watcher; for now this is the
45
- * fallback used on layout changes.
46
- */
47
- refresh(): Promise<void>;
48
- /**
49
- * Add a single entrypoint. Idempotent.
50
- */
51
- add(absolutePath: string): void;
52
- /**
53
- * Remove a single entrypoint. Idempotent.
54
- */
55
- remove(absolutePath: string): void;
56
- /** True if the index contains `absolutePath`. */
57
- has(absolutePath: string): boolean;
58
- /** Snapshot of the current set, sorted by absolute path. */
59
- list(): string[];
60
- /** Number of indexed entrypoints. */
61
- get size(): number;
62
- /** Last refresh timestamp (ms since epoch). */
63
- get refreshedAt(): number;
64
- }
@@ -1,73 +0,0 @@
1
- import path from "node:path";
2
- import { fileSystem } from "@ecopages/file-system";
3
- const DEFAULT_EXTENSIONS = [".tsx", ".kita.tsx", ".lit.tsx", ".eco.tsx", ".mdx", ".react.tsx"];
4
- class PagesIndex {
5
- pagesDir;
6
- extensions;
7
- isPageEntrypoint;
8
- pages = /* @__PURE__ */ new Set();
9
- lastRefreshAt = 0;
10
- constructor(options) {
11
- this.pagesDir = options.pagesDir;
12
- this.extensions = options.extensions ?? DEFAULT_EXTENSIONS;
13
- this.isPageEntrypoint = options.isPageEntrypoint ?? (() => true);
14
- }
15
- /**
16
- * Rescan the pages directory and rebuild the index.
17
- *
18
- * Cheap to call multiple times in sequence (just a glob). The
19
- * real value of `PagesIndex` is the `add` / `remove` path that
20
- * callers can wire to the file watcher; for now this is the
21
- * fallback used on layout changes.
22
- */
23
- async refresh() {
24
- const files = await fileSystem.glob(
25
- this.extensions.map((ext) => `**/*${ext}`),
26
- {
27
- cwd: this.pagesDir
28
- }
29
- );
30
- const next = /* @__PURE__ */ new Set();
31
- for (const file of files) {
32
- const absolutePath = path.join(this.pagesDir, file);
33
- if (!this.isPageEntrypoint(absolutePath)) continue;
34
- if (file.includes(".ecopages-node.")) continue;
35
- next.add(absolutePath);
36
- }
37
- this.pages.clear();
38
- for (const p of next) this.pages.add(p);
39
- this.lastRefreshAt = Date.now();
40
- }
41
- /**
42
- * Add a single entrypoint. Idempotent.
43
- */
44
- add(absolutePath) {
45
- if (!this.isPageEntrypoint(absolutePath)) return;
46
- this.pages.add(absolutePath);
47
- }
48
- /**
49
- * Remove a single entrypoint. Idempotent.
50
- */
51
- remove(absolutePath) {
52
- this.pages.delete(absolutePath);
53
- }
54
- /** True if the index contains `absolutePath`. */
55
- has(absolutePath) {
56
- return this.pages.has(absolutePath);
57
- }
58
- /** Snapshot of the current set, sorted by absolute path. */
59
- list() {
60
- return Array.from(this.pages).sort();
61
- }
62
- /** Number of indexed entrypoints. */
63
- get size() {
64
- return this.pages.size;
65
- }
66
- /** Last refresh timestamp (ms since epoch). */
67
- get refreshedAt() {
68
- return this.lastRefreshAt;
69
- }
70
- }
71
- export {
72
- PagesIndex
73
- };
@@ -1,88 +0,0 @@
1
- /**
2
- * Page module loading and configuration resolution service for React integration.
3
- *
4
- * Handles MDX compilation, component config metadata resolution,
5
- * and module hydration analysis.
6
- *
7
- * @module
8
- */
9
- import type { EcoComponentConfig, EcoPageFile } from '@ecopages/core';
10
- import { type BuildExecutor } from '@ecopages/core/build/build-adapter';
11
- import type { CompileOptions } from '@mdx-js/mdx';
12
- /**
13
- * Configuration for the ReactPageModuleService.
14
- */
15
- export interface ReactPageModuleServiceConfig {
16
- rootDir: string;
17
- distDir: string;
18
- workDir: string;
19
- buildExecutor: BuildExecutor;
20
- layoutsDir?: string;
21
- componentsDir?: string;
22
- mdxCompilerOptions?: CompileOptions;
23
- mdxExtensions: string[];
24
- integrationName: string;
25
- hasRouterAdapter: boolean;
26
- }
27
- /**
28
- * Manages page module loading (including MDX compilation), config metadata
29
- * resolution, and hydration analysis for React pages.
30
- */
31
- export declare class ReactPageModuleService {
32
- private readonly config;
33
- constructor(config: ReactPageModuleServiceConfig);
34
- /**
35
- * Checks if the given file path corresponds to an MDX file based on configured extensions.
36
- * @param filePath - The file path to check
37
- * @returns True if the file is an MDX file
38
- */
39
- isMdxFile(filePath: string): boolean;
40
- /**
41
- * Compiles and imports an MDX file as a page module.
42
- *
43
- * @param filePath - Absolute path to the MDX file
44
- * @returns The imported module
45
- */
46
- importMdxPageFile(filePath: string, options?: {
47
- bypassCache?: boolean;
48
- cacheScope?: string;
49
- }): Promise<EcoPageFile<{
50
- config?: EcoComponentConfig;
51
- }>>;
52
- /**
53
- * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
54
- * Resolves the file path from dependency declarations when not already set.
55
- *
56
- * @param config - The component config to augment
57
- * @param pagePath - Fallback file path if dependency resolution fails
58
- * @returns Config with `__eco` metadata populated
59
- */
60
- ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
61
- /**
62
- * Recursively checks whether a component config tree declares any browser modules.
63
- * Used to determine if a page needs hydration.
64
- */
65
- hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
66
- /**
67
- * Determines whether a page needs client-side hydration.
68
- *
69
- * @param pageModule - The imported page module
70
- * @returns True if the page should be hydrated
71
- */
72
- shouldHydratePage(pageModule: EcoPageFile<{
73
- config?: EcoComponentConfig;
74
- }> & {
75
- config?: EcoComponentConfig;
76
- }): boolean;
77
- /**
78
- * Collects all explicitly declared browser module specifiers from a page module.
79
- *
80
- * @param pageModule - The imported page module
81
- * @returns Deduplicated list of declared module specifiers
82
- */
83
- collectPageDeclaredModules(pageModule: EcoPageFile<{
84
- config?: EcoComponentConfig;
85
- }> & {
86
- config?: EcoComponentConfig;
87
- }): string[];
88
- }
@@ -1,166 +0,0 @@
1
- import path from "node:path";
2
- import { pathToFileURL } from "node:url";
3
- import { build } from "@ecopages/core/build/build-adapter";
4
- import { normalizeNodeRuntimeBuildOutputFile } from "@ecopages/core/build/runtime-build-output-normalizer";
5
- import { rapidhash } from "@ecopages/core/hash";
6
- import { fileSystem } from "@ecopages/file-system";
7
- import { someInConfigTree } from "../utils/component-config-traversal.js";
8
- import { collectDeclaredModulesInConfig } from "../utils/declared-modules.js";
9
- import { createReactMdxLoaderPlugin } from "../utils/react-mdx-loader-plugin.js";
10
- class ReactPageModuleService {
11
- config;
12
- constructor(config) {
13
- this.config = config;
14
- }
15
- /**
16
- * Checks if the given file path corresponds to an MDX file based on configured extensions.
17
- * @param filePath - The file path to check
18
- * @returns True if the file is an MDX file
19
- */
20
- isMdxFile(filePath) {
21
- return this.config.mdxExtensions.some((ext) => filePath.endsWith(ext));
22
- }
23
- /**
24
- * Compiles and imports an MDX file as a page module.
25
- *
26
- * @param filePath - Absolute path to the MDX file
27
- * @returns The imported module
28
- */
29
- async importMdxPageFile(filePath, options) {
30
- const mdxPlugin = createReactMdxLoaderPlugin(
31
- this.config.mdxCompilerOptions ?? {
32
- jsxImportSource: "react",
33
- jsxRuntime: "automatic",
34
- development: process?.env?.NODE_ENV === "development"
35
- }
36
- );
37
- const outdir = path.join(this.config.workDir, ".server-modules-react-mdx");
38
- const fileBaseName = path.basename(filePath, path.extname(filePath));
39
- const fileHash = fileSystem.hash(filePath);
40
- const cacheScopeSuffix = options?.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : "";
41
- const cacheBuster = options?.bypassCache || process?.env?.NODE_ENV === "development" ? `-${Date.now()}` : "";
42
- const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${cacheBuster}.mjs`;
43
- const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${cacheBuster}.[ext]`;
44
- const buildResult = await build(
45
- {
46
- entrypoints: [filePath],
47
- root: this.config.rootDir,
48
- outdir,
49
- target: "es2022",
50
- format: "esm",
51
- sourcemap: "none",
52
- splitting: false,
53
- minify: false,
54
- treeshaking: false,
55
- externalPackages: true,
56
- naming: outputNamingTemplate,
57
- plugins: [mdxPlugin]
58
- },
59
- this.config.buildExecutor
60
- );
61
- if (!buildResult.success) {
62
- const details = buildResult.logs.map((log) => log.message).join(" | ");
63
- throw new Error(`Failed to compile MDX page module: ${details}`);
64
- }
65
- const preferredOutputPath = path.join(outdir, outputFileName);
66
- const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
67
- if (!compiledOutput) {
68
- throw new Error(`No compiled MDX output generated for page: ${filePath}`);
69
- }
70
- normalizeNodeRuntimeBuildOutputFile(compiledOutput, this.config.rootDir);
71
- const compiledOutputUrl = pathToFileURL(compiledOutput);
72
- if (process?.env?.NODE_ENV === "development" || options?.cacheScope) {
73
- compiledOutputUrl.searchParams.set(
74
- "update",
75
- [fileHash, options?.cacheScope ? sanitizeCacheScope(options.cacheScope) : void 0].filter((value) => value !== void 0).join("-")
76
- );
77
- }
78
- return await import(
79
- /* @vite-ignore */
80
- compiledOutputUrl.href
81
- );
82
- }
83
- /**
84
- * Ensures that an EcoComponentConfig has proper `__eco` metadata attached.
85
- * Resolves the file path from dependency declarations when not already set.
86
- *
87
- * @param config - The component config to augment
88
- * @param pagePath - Fallback file path if dependency resolution fails
89
- * @returns Config with `__eco` metadata populated
90
- */
91
- ensureConfigFileMetadata(config, pagePath) {
92
- if (config.__eco?.file) {
93
- return config;
94
- }
95
- const buildEcoMeta = (file) => ({
96
- id: config.__eco?.id ?? rapidhash(file).toString(36),
97
- integration: config.__eco?.integration ?? this.config.integrationName,
98
- file
99
- });
100
- const resolveDependencyValue = (value) => typeof value === "string" ? value : value.src;
101
- const dependencyPaths = [
102
- ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
103
- ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue)
104
- ].filter((value) => Boolean(value)).filter((value) => value.startsWith("./") || value.startsWith("../"));
105
- const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter(
106
- (value) => typeof value === "string" && value.length > 0
107
- );
108
- for (const dependencyPath of dependencyPaths) {
109
- for (const candidateDir of candidateDirs) {
110
- const resolvedDependency = path.resolve(candidateDir, dependencyPath);
111
- if (fileSystem.exists(resolvedDependency)) {
112
- return {
113
- ...config,
114
- __eco: buildEcoMeta(path.join(candidateDir, path.basename(pagePath)))
115
- };
116
- }
117
- }
118
- }
119
- return {
120
- ...config,
121
- __eco: buildEcoMeta(pagePath)
122
- };
123
- }
124
- /**
125
- * Recursively checks whether a component config tree declares any browser modules.
126
- * Used to determine if a page needs hydration.
127
- */
128
- hasModulesInConfig(config) {
129
- return someInConfigTree(
130
- config,
131
- (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false
132
- );
133
- }
134
- /**
135
- * Determines whether a page needs client-side hydration.
136
- *
137
- * @param pageModule - The imported page module
138
- * @returns True if the page should be hydrated
139
- */
140
- shouldHydratePage(pageModule) {
141
- if (this.config.hasRouterAdapter) {
142
- return true;
143
- }
144
- const pageConfig = pageModule.default?.config;
145
- return this.hasModulesInConfig(pageConfig) || this.hasModulesInConfig(pageModule.config);
146
- }
147
- /**
148
- * Collects all explicitly declared browser module specifiers from a page module.
149
- *
150
- * @param pageModule - The imported page module
151
- * @returns Deduplicated list of declared module specifiers
152
- */
153
- collectPageDeclaredModules(pageModule) {
154
- const declarations = [
155
- ...collectDeclaredModulesInConfig(pageModule.default?.config),
156
- ...collectDeclaredModulesInConfig(pageModule.config)
157
- ];
158
- return Array.from(new Set(declarations));
159
- }
160
- }
161
- function sanitizeCacheScope(cacheScope) {
162
- return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
163
- }
164
- export {
165
- ReactPageModuleService
166
- };
@@ -1,46 +0,0 @@
1
- import type { HtmlTemplateProps, IntegrationRendererRenderOptions, RequestLocals } from '@ecopages/core';
2
- import type { ReactNode } from 'react';
3
- type PagePayloadOptions = {
4
- pageProps?: HtmlTemplateProps['pageProps'];
5
- params: IntegrationRendererRenderOptions<ReactNode>['params'];
6
- query: IntegrationRendererRenderOptions<ReactNode>['query'];
7
- safeLocals?: RequestLocals;
8
- };
9
- /**
10
- * Builds the serialized page payload React exposes to document shells and the browser.
11
- *
12
- * This keeps hydration payload shaping away from the renderer so the renderer can
13
- * stay focused on component orchestration instead of data serialization rules.
14
- */
15
- export declare class ReactPagePayloadService {
16
- /**
17
- * Creates the canonical page-props payload used by router hydration.
18
- *
19
- * React pages embedded in a non-React HTML shell still need to expose the same
20
- * page-data contract as fully React-owned documents so navigation and hydration
21
- * can read one shared document payload consistently.
22
- */
23
- buildRouterPageDataScript(pageProps: HtmlTemplateProps['pageProps'] | undefined): string;
24
- /**
25
- * Builds the serialized page-props payload embedded into the final HTML.
26
- *
27
- * The document payload is intentionally narrower than the full server render
28
- * input: only routing data, public page props, and explicitly allowed locals are
29
- * exposed to the browser.
30
- */
31
- buildSerializedPageProps(options: PagePayloadOptions): HtmlTemplateProps['pageProps'];
32
- /**
33
- * Safely extracts the declared subset of locals for client-side hydration.
34
- *
35
- * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
36
- * request-scoped data (e.g., session). Only keys explicitly declared via
37
- * `Page.requires` are serialized to the client so sensitive request-only data
38
- * is not leaked into hydration payloads by default.
39
- *
40
- * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
41
- * to prevent accidental use. This method safely detects that case and returns
42
- * `undefined` instead of throwing.
43
- */
44
- getSerializableLocals(locals: RequestLocals | undefined, requiredLocals?: string | readonly string[]): RequestLocals | undefined;
45
- }
46
- export {};
@@ -1,67 +0,0 @@
1
- import { LocalsAccessError } from "@ecopages/core/errors";
2
- class ReactPagePayloadService {
3
- /**
4
- * Creates the canonical page-props payload used by router hydration.
5
- *
6
- * React pages embedded in a non-React HTML shell still need to expose the same
7
- * page-data contract as fully React-owned documents so navigation and hydration
8
- * can read one shared document payload consistently.
9
- */
10
- buildRouterPageDataScript(pageProps) {
11
- const safeJson = JSON.stringify(pageProps || {}).replace(/</g, "\\u003c");
12
- return `<script id="__ECO_PAGE_DATA__" type="application/json">${safeJson}<\/script>`;
13
- }
14
- /**
15
- * Builds the serialized page-props payload embedded into the final HTML.
16
- *
17
- * The document payload is intentionally narrower than the full server render
18
- * input: only routing data, public page props, and explicitly allowed locals are
19
- * exposed to the browser.
20
- */
21
- buildSerializedPageProps(options) {
22
- return {
23
- ...options.pageProps,
24
- params: options.params,
25
- query: options.query,
26
- ...options.safeLocals && { locals: options.safeLocals }
27
- };
28
- }
29
- /**
30
- * Safely extracts the declared subset of locals for client-side hydration.
31
- *
32
- * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
33
- * request-scoped data (e.g., session). Only keys explicitly declared via
34
- * `Page.requires` are serialized to the client so sensitive request-only data
35
- * is not leaked into hydration payloads by default.
36
- *
37
- * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
38
- * to prevent accidental use. This method safely detects that case and returns
39
- * `undefined` instead of throwing.
40
- */
41
- getSerializableLocals(locals, requiredLocals) {
42
- try {
43
- if (!locals) {
44
- return void 0;
45
- }
46
- const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
47
- if (requiredKeys.length === 0) {
48
- return void 0;
49
- }
50
- const serializedLocals = Object.fromEntries(
51
- requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
52
- );
53
- if (Object.keys(serializedLocals).length > 0) {
54
- return serializedLocals;
55
- }
56
- return void 0;
57
- } catch (error) {
58
- if (error instanceof LocalsAccessError) {
59
- return void 0;
60
- }
61
- throw error;
62
- }
63
- }
64
- }
65
- export {
66
- ReactPagePayloadService
67
- };
@@ -1,92 +0,0 @@
1
- /**
2
- * Hydration script generators for React pages.
3
- * These functions create the page entry modules that hydrate React routes.
4
- * @module
5
- */
6
- import type { ReactRouterAdapter } from '../router-adapter.js';
7
- /**
8
- * Options for generating a hydration script.
9
- */
10
- export type HydrationScriptOptions = {
11
- /** The module path imported by the page entry module. */
12
- importPath: string;
13
- /** Browser expression that resolves to the page module URL the router should import. */
14
- pageModuleUrlExpression?: string;
15
- /** Stable id of the page entry script tag in the document. */
16
- scriptId: string;
17
- /** Direct import path for React runtime module */
18
- reactImportPath: string;
19
- /** Direct import path for react-dom/client runtime module */
20
- reactDomClientImportPath: string;
21
- /** Direct import path for router runtime module */
22
- routerImportPath?: string;
23
- /** Whether running in development mode with HMR support */
24
- isDevelopment: boolean;
25
- /** Whether the source file is an MDX file */
26
- isMdx: boolean;
27
- /** Optional router adapter for SPA navigation */
28
- router?: ReactRouterAdapter;
29
- };
30
- export type IslandHydrationScriptOptions = {
31
- /** Bundled browser module path for the island component. */
32
- importPath: string;
33
- /** Stable id of the island bootstrap script tag in the document. */
34
- scriptId: string;
35
- /** Browser import path for React runtime. */
36
- reactImportPath: string;
37
- /** Browser import path for react-dom/client runtime. */
38
- reactDomClientImportPath: string;
39
- /** Selector that resolves to all SSR root elements for this island component. */
40
- targetSelector: string;
41
- /** Optional stable component id used to resolve named exports reliably. */
42
- componentRef?: string;
43
- /** Optional source file hint used as fallback for component resolution. */
44
- componentFile?: string;
45
- /** Enables development-oriented non-minified output. */
46
- isDevelopment: boolean;
47
- };
48
- /**
49
- * Creates a hydration script for client-side React hydration.
50
- *
51
- * Why this dispatcher exists:
52
- * the runtime matrix is small but behaviorally different across development vs
53
- * production and router vs non-router pages. Keeping that branch here preserves
54
- * a compact public API while allowing each emitted script to stay focused.
55
- *
56
- * Selection rules:
57
- * - development uses readable scripts with HMR hooks
58
- * - production uses minified equivalents
59
- * - router presence decides whether page updates flow through the router runtime
60
- * or rebuild directly from the page module
61
- *
62
- * @param options - Configuration options for script generation
63
- * @returns The generated hydration script as a string
64
- */
65
- export declare function createHydrationScript(options: HydrationScriptOptions): string;
66
- /**
67
- * Creates the client bootstrap for component-level React islands.
68
- *
69
- * The island runtime intentionally uses `createRoot()` (not `hydrateRoot()`) and
70
- * mounts into the SSR element identified by `targetSelector`.
71
- *
72
- * Rationale:
73
- * - No synthetic wrapper element is introduced in SSR output.
74
- * - DOM structure remains identical to authored component markup.
75
- * - Runtime ownership is isolated per island instance.
76
- *
77
- * Generated script behavior:
78
- * - resolves the component export by metadata (`componentRef`, `componentFile`)
79
- * before falling back to default/first function export
80
- * - selects island root using `targetSelector`
81
- * - replaces the SSR host with a dedicated client-owned container
82
- * - creates a fresh React root and renders with serialized `props`
83
- *
84
- * Why it remounts instead of hydrating:
85
- * island SSR intentionally avoids synthetic wrapper elements. The runtime swaps
86
- * the authored SSR node for a dedicated client-owned container before mounting
87
- * so the server markup stays clean while the client still gets a stable root.
88
- *
89
- * @param options Island script generation options.
90
- * @returns Browser-executable JavaScript module source.
91
- */
92
- export declare function createIslandHydrationScript(options: IslandHydrationScriptOptions): string;