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

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 (57) hide show
  1. package/README.md +5 -1
  2. package/package.json +4 -4
  3. package/src/app/client-only.js +13 -17
  4. package/src/app/dynamic.js +7 -10
  5. package/src/app/dynamic.test.browser.js +27 -29
  6. package/src/bundling/bootstrap-package-paths.js +5 -6
  7. package/src/bundling/bundle.js +115 -114
  8. package/src/bundling/discover-layout-runtime-modules.js +166 -155
  9. package/src/bundling/runtime-alias-map.d.ts +4 -1
  10. package/src/bundling/runtime-alias-map.js +107 -95
  11. package/src/bundling/runtime-bundle.js +250 -274
  12. package/src/bundling/runtime-interop-plugin.js +31 -35
  13. package/src/bundling/runtime-mode.js +10 -5
  14. package/src/bundling/runtime-modules.js +46 -35
  15. package/src/client-graph/ast-transform.js +415 -305
  16. package/src/client-graph/boundary-cache.js +146 -104
  17. package/src/client-graph/boundary-plugin.js +122 -104
  18. package/src/client-graph/component-config-traversal.js +70 -49
  19. package/src/client-graph/declared-modules.js +63 -41
  20. package/src/client-graph/reachability-analyzer.js +506 -313
  21. package/src/client-graph/specifier-classification.js +209 -141
  22. package/src/contracts/router-adapter.js +6 -0
  23. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  24. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  25. package/src/hmr/hmr-scripts.js +22 -9
  26. package/src/hmr/hmr-strategy.d.ts +12 -181
  27. package/src/hmr/hmr-strategy.js +321 -650
  28. package/src/hmr/page-metadata-cache.js +43 -40
  29. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  30. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  31. package/src/hydration/assert-no-bare-ecopages-imports.js +6 -6
  32. package/src/hydration/bootstrap-imports.js +30 -20
  33. package/src/hydration/hydration-asset.js +216 -213
  34. package/src/hydration/hydration-scripts.d.ts +4 -0
  35. package/src/hydration/hydration-scripts.js +199 -66
  36. package/src/hydration/hydration-scripts.test.browser.js +163 -168
  37. package/src/hydration/page-data-manifest.js +89 -45
  38. package/src/hydration/page-data-reader.js +45 -32
  39. package/src/hydration/page-payload.js +101 -99
  40. package/src/hydration/serialize-page-data-script.js +27 -28
  41. package/src/mdx/mdx-config-dependency.js +108 -112
  42. package/src/mdx/mdx-loader-plugin.js +7 -10
  43. package/src/page/page-module.js +72 -66
  44. package/src/plugin/react.constants.js +1 -4
  45. package/src/plugin/react.plugin.d.ts +1 -0
  46. package/src/plugin/react.plugin.js +227 -216
  47. package/src/plugin/react.types.js +1 -0
  48. package/src/render/component-ownership.js +42 -18
  49. package/src/render/component-ssr.js +168 -190
  50. package/src/render/eco-embed.js +8 -10
  51. package/src/render/errors.js +21 -16
  52. package/src/render/html-boundary.js +55 -51
  53. package/src/render/layout-compose.js +122 -94
  54. package/src/render/react-renderer.js +433 -468
  55. package/src/render/react-runtime.js +25 -20
  56. package/src/render/unified-layout-composition.js +74 -85
  57. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
@@ -1,104 +1,106 @@
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;
1
+ import { LocalsAccessError } from '@ecopages/core/errors';
2
+ import { serializePageDataManifestScript, serializePageDataScript, } from './serialize-page-data-script.js';
3
+ import { isReactManagedComponent } from '../render/component-ownership.js';
4
+ /**
5
+ * Builds the serialized page payload React exposes to document shells and the browser.
6
+ *
7
+ * @remarks
8
+ * Keeps hydration payload shaping away from the renderer so orchestration stays
9
+ * focused on component composition instead of document serialization rules.
10
+ */
11
+ export class PagePayloadService {
12
+ /**
13
+ * Resolves the browser-importable page module URL from processed page entry assets.
14
+ */
15
+ resolvePageModuleUrl(pagePackage, options) {
16
+ if (!options.routerEnabled) {
17
+ return undefined;
18
+ }
19
+ const entryScripts = pagePackage?.pageBrowserGraph?.entryAssets.filter((asset) => asset.kind === 'script' && typeof asset.srcUrl === 'string') ?? [];
20
+ const bootstrapScript = entryScripts.find((asset) => asset.attributes?.['data-eco-page-bootstrap'] === 'react-router');
21
+ return bootstrapScript?.srcUrl ?? entryScripts[0]?.srcUrl;
14
22
  }
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 });
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);
35
37
  }
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;
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 undefined;
45
+ }
46
+ return [
47
+ {
48
+ placement: 'head-append',
49
+ html: this.buildRouterPageDataScript(options.pageProps, options.pageModuleUrl),
50
+ },
51
+ ];
45
52
  }
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;
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 undefined;
82
+ }
83
+ const requiredKeys = requiredLocals
84
+ ? Array.isArray(requiredLocals)
85
+ ? requiredLocals
86
+ : [requiredLocals]
87
+ : [];
88
+ if (requiredKeys.length === 0) {
89
+ return undefined;
90
+ }
91
+ const serializedLocals = Object.fromEntries(requiredKeys
92
+ .filter((key) => Object.prototype.hasOwnProperty.call(locals, key))
93
+ .map((key) => [key, locals[key]]));
94
+ if (Object.keys(serializedLocals).length > 0) {
95
+ return serializedLocals;
96
+ }
97
+ return undefined;
98
+ }
99
+ catch (error) {
100
+ if (error instanceof LocalsAccessError) {
101
+ return undefined;
102
+ }
103
+ throw error;
104
+ }
99
105
  }
100
- }
101
106
  }
102
- export {
103
- PagePayloadService
104
- };
@@ -1,31 +1,30 @@
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");
1
+ import { createEcoPageDataManifestV1, } from './page-data-manifest.js';
2
+ export { ECO_PAGE_DATA_SCHEMA_VERSION, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolvePageDataDocumentPayload, } from './page-data-manifest.js';
3
+ /**
4
+ * Escapes page data JSON for safe embedding in HTML script bodies.
5
+ */
6
+ export function escapePageDataJson(pageProps) {
7
+ return JSON.stringify(pageProps ?? {}).replace(/</g, '\\u003c');
14
8
  }
15
- function serializePageDataScript(pageProps) {
16
- return `<script id="__ECO_PAGE_DATA__" type="application/json">${escapePageDataJson(pageProps)}<\/script>`;
9
+ /**
10
+ * Emits the canonical `__ECO_PAGE_DATA__` bootstrap script tag.
11
+ *
12
+ * @remarks
13
+ * Accepts a v1 envelope or legacy flat props. Router-enabled documents should
14
+ * use {@link serializePageDataManifestScript} so clients can discover the page
15
+ * module without parsing hydration JavaScript.
16
+ */
17
+ export function serializePageDataScript(pageProps) {
18
+ return `<script id="__ECO_PAGE_DATA__" type="application/json">${escapePageDataJson(pageProps)}</script>`;
17
19
  }
18
- function serializePageDataManifestScript(input) {
19
- return serializePageDataScript(createEcoPageDataManifestV1(input));
20
+ /**
21
+ * Emits a versioned page-data envelope for React router documents.
22
+ *
23
+ * @remarks
24
+ * Canonical HTML serializer for router-enabled pages. SPA commit paths that
25
+ * build a React element instead of an HTML string use
26
+ * {@link resolvePageDataDocumentPayload} with the same envelope shape.
27
+ */
28
+ export function serializePageDataManifestScript(input) {
29
+ return serializePageDataScript(createEcoPageDataManifestV1(input));
20
30
  }
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,120 +1,116 @@
1
- import path from "node:path";
2
- import { rapidhash } from "@ecopages/core/hash";
3
- import {
4
- AssetFactory
5
- } from "@ecopages/core/services/asset-processing-service";
6
- import { collectFromConfigForest, getComponentConfigs } from "../client-graph/component-config-traversal.js";
7
- class MdxConfigDependencyService {
8
- config;
9
- constructor(config) {
10
- this.config = config;
11
- }
12
- /**
13
- * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
14
- */
15
- async processMdxConfigDependencies(options) {
16
- const components = this.createOwnedConfigComponents(options.pagePath, options.config);
17
- if (components.length === 0) {
18
- return [];
1
+ import path from 'node:path';
2
+ import { rapidhash } from '@ecopages/core/hash';
3
+ import { AssetFactory, } from '@ecopages/core/services/asset-processing-service';
4
+ import { collectFromConfigForest, getComponentConfigs } from '../client-graph/component-config-traversal.js';
5
+ /**
6
+ * Resolves MDX-owned config dependencies that live outside the normal React component tree.
7
+ *
8
+ * React MDX pages can declare dependencies on the page config itself or on a
9
+ * resolved layout config. Those roots need to be materialized as synthetic
10
+ * component configs so the shared dependency pipeline can process them without
11
+ * growing more MDX-specific logic inside the renderer.
12
+ */
13
+ export class MdxConfigDependencyService {
14
+ config;
15
+ constructor(config) {
16
+ this.config = config;
19
17
  }
20
- const processedDependencies = await options.processComponentDependencies(components);
21
- const eagerSsrLazyDependencies = await this.processDeclaredSsrLazyDependencies(components, options.pagePath);
22
- return [...processedDependencies, ...eagerSsrLazyDependencies];
23
- }
24
- createOwnedConfigComponents(pagePath, config) {
25
- const components = [];
26
- for (const layout of config?.layouts ?? []) {
27
- if (layout?.config?.dependencies) {
28
- const layoutConfig = this.config.pageModuleService.ensureConfigFileMetadata(layout.config, pagePath);
29
- components.push({ config: layoutConfig });
30
- }
31
- }
32
- if (config?.dependencies) {
33
- components.push({
34
- config: {
35
- ...config,
36
- __eco: {
37
- id: rapidhash(pagePath).toString(36),
38
- file: pagePath,
39
- integration: this.config.integrationName
40
- }
18
+ /**
19
+ * Processes MDX-owned config dependencies and eagerly emits any SSR-marked lazy scripts.
20
+ */
21
+ async processMdxConfigDependencies(options) {
22
+ const components = this.createOwnedConfigComponents(options.pagePath, options.config);
23
+ if (components.length === 0) {
24
+ return [];
41
25
  }
42
- });
43
- }
44
- return components;
45
- }
46
- async processDeclaredSsrLazyDependencies(components, pagePath) {
47
- if (!this.config.assetProcessingService?.processDependencies) {
48
- return [];
49
- }
50
- const dependencies = this.collectDeclaredSsrLazyDependencies(components);
51
- if (dependencies.length === 0) {
52
- return [];
26
+ const processedDependencies = await options.processComponentDependencies(components);
27
+ const eagerSsrLazyDependencies = await this.processDeclaredSsrLazyDependencies(components, options.pagePath);
28
+ return [...processedDependencies, ...eagerSsrLazyDependencies];
53
29
  }
54
- return this.config.assetProcessingService.processDependencies(
55
- dependencies,
56
- `${this.config.integrationName}-mdx-ssr-lazy:${pagePath}`
57
- );
58
- }
59
- /**
60
- * Collects `lazy` script dependencies that also opt into SSR from an MDX config graph.
61
- */
62
- collectDeclaredSsrLazyDependencies(components) {
63
- const dependencies = [];
64
- const seenKeys = /* @__PURE__ */ new Set();
65
- const normalizeAttributes = (attributes) => ({
66
- type: "module",
67
- defer: "",
68
- ...attributes ?? {}
69
- });
70
- collectFromConfigForest(getComponentConfigs(components), (config) => {
71
- const componentFile = config.__eco?.file;
72
- if (!componentFile) {
73
- return [];
74
- }
75
- const componentDir = path.dirname(componentFile);
76
- for (const script of config.dependencies?.scripts ?? []) {
77
- if (typeof script === "string" || !script.lazy || script.ssr !== true) {
78
- continue;
30
+ createOwnedConfigComponents(pagePath, config) {
31
+ const components = [];
32
+ for (const layout of config?.layouts ?? []) {
33
+ if (layout?.config?.dependencies) {
34
+ const layoutConfig = this.config.pageModuleService.ensureConfigFileMetadata(layout.config, pagePath);
35
+ components.push({ config: layoutConfig });
36
+ }
79
37
  }
80
- const attributes = normalizeAttributes(script.attributes);
81
- if (script.content) {
82
- const key2 = `content:${script.content}:${JSON.stringify(attributes)}`;
83
- if (seenKeys.has(key2)) {
84
- continue;
85
- }
86
- seenKeys.add(key2);
87
- dependencies.push(
88
- AssetFactory.createContentScript({
89
- position: "head",
90
- content: script.content,
91
- attributes
92
- })
93
- );
94
- continue;
38
+ if (config?.dependencies) {
39
+ components.push({
40
+ config: {
41
+ ...config,
42
+ __eco: {
43
+ id: rapidhash(pagePath).toString(36),
44
+ file: pagePath,
45
+ integration: this.config.integrationName,
46
+ },
47
+ },
48
+ });
95
49
  }
96
- if (!script.src) {
97
- continue;
50
+ return components;
51
+ }
52
+ async processDeclaredSsrLazyDependencies(components, pagePath) {
53
+ if (!this.config.assetProcessingService?.processDependencies) {
54
+ return [];
98
55
  }
99
- const resolvedPath = path.resolve(componentDir, script.src);
100
- const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
101
- if (seenKeys.has(key)) {
102
- continue;
56
+ const dependencies = this.collectDeclaredSsrLazyDependencies(components);
57
+ if (dependencies.length === 0) {
58
+ return [];
103
59
  }
104
- seenKeys.add(key);
105
- dependencies.push(
106
- AssetFactory.createFileScript({
107
- filepath: resolvedPath,
108
- position: "head",
109
- attributes
110
- })
111
- );
112
- }
113
- return [];
114
- });
115
- return dependencies;
116
- }
60
+ return this.config.assetProcessingService.processDependencies(dependencies, `${this.config.integrationName}-mdx-ssr-lazy:${pagePath}`);
61
+ }
62
+ /**
63
+ * Collects `lazy` script dependencies that also opt into SSR from an MDX config graph.
64
+ */
65
+ collectDeclaredSsrLazyDependencies(components) {
66
+ const dependencies = [];
67
+ const seenKeys = new Set();
68
+ const normalizeAttributes = (attributes) => ({
69
+ type: 'module',
70
+ defer: '',
71
+ ...(attributes ?? {}),
72
+ });
73
+ collectFromConfigForest(getComponentConfigs(components), (config) => {
74
+ const componentFile = config.__eco?.file;
75
+ if (!componentFile) {
76
+ return [];
77
+ }
78
+ const componentDir = path.dirname(componentFile);
79
+ for (const script of config.dependencies?.scripts ?? []) {
80
+ if (typeof script === 'string' || !script.lazy || script.ssr !== true) {
81
+ continue;
82
+ }
83
+ const attributes = normalizeAttributes(script.attributes);
84
+ if (script.content) {
85
+ const key = `content:${script.content}:${JSON.stringify(attributes)}`;
86
+ if (seenKeys.has(key)) {
87
+ continue;
88
+ }
89
+ seenKeys.add(key);
90
+ dependencies.push(AssetFactory.createContentScript({
91
+ position: 'head',
92
+ content: script.content,
93
+ attributes,
94
+ }));
95
+ continue;
96
+ }
97
+ if (!script.src) {
98
+ continue;
99
+ }
100
+ const resolvedPath = path.resolve(componentDir, script.src);
101
+ const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
102
+ if (seenKeys.has(key)) {
103
+ continue;
104
+ }
105
+ seenKeys.add(key);
106
+ dependencies.push(AssetFactory.createFileScript({
107
+ filepath: resolvedPath,
108
+ position: 'head',
109
+ attributes,
110
+ }));
111
+ }
112
+ return [];
113
+ });
114
+ return dependencies;
115
+ }
117
116
  }
118
- export {
119
- MdxConfigDependencyService
120
- };
@@ -1,11 +1,8 @@
1
- import { createMdxLoaderPlugin as createMdxLoaderPluginCore } from "@ecopages/mdx/core";
2
- function createReactMdxLoaderPlugin(compilerOptions) {
3
- return createMdxLoaderPluginCore({
4
- name: "react-mdx-loader",
5
- compilerOptions,
6
- defaultMdExtensions: []
7
- });
1
+ import { createMdxLoaderPlugin as createMdxLoaderPluginCore } from '@ecopages/mdx/core';
2
+ export function createReactMdxLoaderPlugin(compilerOptions) {
3
+ return createMdxLoaderPluginCore({
4
+ name: 'react-mdx-loader',
5
+ compilerOptions,
6
+ defaultMdExtensions: [],
7
+ });
8
8
  }
9
- export {
10
- createReactMdxLoaderPlugin
11
- };