@ecopages/react 0.2.0-beta.31 → 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,155 +1,223 @@
1
- import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from "@ecopages/core/plugins/tsconfig-import-resolver";
2
- import { dirname, resolve } from "node:path";
3
- function isBareSpecifier(specifier) {
4
- if (specifier.startsWith(".")) return false;
5
- if (specifier.startsWith("/")) return false;
6
- if (specifier.includes("://")) return false;
7
- return true;
8
- }
9
- function isProjectAliasSpecifier(specifier, projectRoot) {
10
- if (specifier.startsWith("ecopages:")) {
1
+ /**
2
+ * Specifier classification and requested-export registry helpers for the client graph boundary.
3
+ */
4
+ import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from '@ecopages/core/plugins/tsconfig-import-resolver';
5
+ import { dirname, resolve } from 'node:path';
6
+ export function isBareSpecifier(specifier) {
7
+ if (specifier.startsWith('.'))
8
+ return false;
9
+ if (specifier.startsWith('/'))
10
+ return false;
11
+ if (specifier.includes('://'))
12
+ return false;
11
13
  return true;
12
- }
13
- if (projectRoot) {
14
- return matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot));
15
- }
16
- return false;
17
14
  }
18
- function isServerOnlySpecifier(specifier) {
19
- if (specifier.startsWith("node:")) return true;
20
- return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
15
+ export function isProjectAliasSpecifier(specifier, projectRoot) {
16
+ if (specifier.startsWith('ecopages:')) {
17
+ return true;
18
+ }
19
+ if (projectRoot) {
20
+ return matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot));
21
+ }
22
+ return false;
21
23
  }
22
- function toModuleBaseSpecifier(specifier) {
23
- if (!isBareSpecifier(specifier) || specifier.startsWith("node:")) {
24
- return specifier;
25
- }
26
- if (specifier.startsWith("@")) {
27
- const [scope, name2] = specifier.split("/");
28
- if (!scope || !name2) return specifier;
29
- return `${scope}/${name2}`;
30
- }
31
- const [name] = specifier.split("/");
32
- return name ?? specifier;
24
+ /**
25
+ * Determines whether a specifier should be treated as server-only.
26
+ *
27
+ * This covers Node built-ins as well as local module conventions such as
28
+ * `.server.ts` and extensionless imports that resolve to `.server.*` files.
29
+ *
30
+ * @param specifier - Raw import specifier from the module source.
31
+ * @returns True when the import must never become client-reachable.
32
+ */
33
+ export function isServerOnlySpecifier(specifier) {
34
+ if (specifier.startsWith('node:'))
35
+ return true;
36
+ return /(?:^|[/])[^/]+\.server(?:$|\.)/.test(specifier);
33
37
  }
34
- function parseDeclaredModules(moduleDeclarations) {
35
- const map = /* @__PURE__ */ new Map();
36
- for (const declaration of moduleDeclarations ?? []) {
37
- const source = declaration.trim();
38
- if (source.length === 0) continue;
39
- const openBraceIndex = source.indexOf("{");
40
- if (openBraceIndex < 0) {
41
- map.set(toModuleBaseSpecifier(source), "*");
42
- continue;
43
- }
44
- const closeBraceIndex = source.indexOf("}", openBraceIndex);
45
- const rawPkg = source.slice(0, openBraceIndex).trim();
46
- if (rawPkg.length === 0) continue;
47
- const pkg = toModuleBaseSpecifier(rawPkg);
48
- const namedImportsStr = closeBraceIndex > openBraceIndex ? source.slice(openBraceIndex + 1, closeBraceIndex) : source.slice(openBraceIndex + 1);
49
- const namedImports = namedImportsStr.split(",").map((s) => s.trim()).filter(Boolean);
50
- const existing = map.get(pkg);
51
- if (existing === "*") continue;
52
- if (!existing) {
53
- if (namedImports.length === 0) {
54
- map.set(pkg, "*");
55
- } else {
56
- map.set(pkg, new Set(namedImports));
57
- }
58
- } else {
59
- for (const name of namedImports) {
60
- existing.add(name);
61
- }
62
- }
63
- }
64
- return map;
38
+ /**
39
+ * Strips down a deep path module specifier to its foundational root package name.
40
+ *
41
+ * When checking against the "allowed modules" whitelist, a component might import something deeply
42
+ * nested like `lodash/fp/map` or `@myorg/ui/button`. However, the user configuration only whitelists
43
+ * the root `lodash` or `@myorg/ui` package. This normalizer ensures we are comparing apples to apples
44
+ * by extracting the base package scope before checking the authorization list.
45
+ *
46
+ * @example
47
+ * toModuleBaseSpecifier('@scope/package/deep/file') -> '@scope/package'
48
+ * toModuleBaseSpecifier('lodash/cloneDeep') -> 'lodash'
49
+ * toModuleBaseSpecifier('node:fs') -> 'node:fs'
50
+ *
51
+ * @param specifier - The raw import specifier from the code.
52
+ * @returns The root package name, preserving scoped npm organizations.
53
+ */
54
+ export function toModuleBaseSpecifier(specifier) {
55
+ if (!isBareSpecifier(specifier) || specifier.startsWith('node:')) {
56
+ return specifier;
57
+ }
58
+ if (specifier.startsWith('@')) {
59
+ const [scope, name] = specifier.split('/');
60
+ if (!scope || !name)
61
+ return specifier;
62
+ return `${scope}/${name}`;
63
+ }
64
+ const [name] = specifier.split('/');
65
+ return name ?? specifier;
65
66
  }
66
- function mergeDeclaredModulesMap(a, b) {
67
- const result = new Map(a);
68
- for (const [pkg, imports] of b.entries()) {
69
- const existing = result.get(pkg);
70
- if (existing === "*") continue;
71
- if (imports === "*") {
72
- result.set(pkg, "*");
73
- continue;
67
+ /**
68
+ * Parses the grammar syntax of declared modules.
69
+ * Handles patterns like `@pkg/name` and `@pkg/name{namedImport,anotherImport}`
70
+ * returning a map of base packages to their explicitly allowed specifiers.
71
+ *
72
+ * @param moduleDeclarations - A list of module declaration strings.
73
+ * @returns A structured map of allowed packages and their named exports.
74
+ */
75
+ export function parseDeclaredModules(moduleDeclarations) {
76
+ const map = new Map();
77
+ for (const declaration of moduleDeclarations ?? []) {
78
+ const source = declaration.trim();
79
+ if (source.length === 0)
80
+ continue;
81
+ const openBraceIndex = source.indexOf('{');
82
+ if (openBraceIndex < 0) {
83
+ map.set(toModuleBaseSpecifier(source), '*');
84
+ continue;
85
+ }
86
+ const closeBraceIndex = source.indexOf('}', openBraceIndex);
87
+ const rawPkg = source.slice(0, openBraceIndex).trim();
88
+ if (rawPkg.length === 0)
89
+ continue;
90
+ const pkg = toModuleBaseSpecifier(rawPkg);
91
+ const namedImportsStr = closeBraceIndex > openBraceIndex
92
+ ? source.slice(openBraceIndex + 1, closeBraceIndex)
93
+ : source.slice(openBraceIndex + 1);
94
+ const namedImports = namedImportsStr
95
+ .split(',')
96
+ .map((s) => s.trim())
97
+ .filter(Boolean);
98
+ const existing = map.get(pkg);
99
+ if (existing === '*')
100
+ continue;
101
+ if (!existing) {
102
+ if (namedImports.length === 0) {
103
+ map.set(pkg, '*');
104
+ }
105
+ else {
106
+ map.set(pkg, new Set(namedImports));
107
+ }
108
+ }
109
+ else {
110
+ for (const name of namedImports) {
111
+ existing.add(name);
112
+ }
113
+ }
74
114
  }
75
- if (!existing) {
76
- result.set(pkg, imports);
77
- } else {
78
- for (const name of imports) {
79
- existing.add(name);
80
- }
81
- }
82
- }
83
- return result;
115
+ return map;
84
116
  }
85
- function normalizeRequestedExportsKey(pathname) {
86
- let normalized = pathname.replace(/\\/g, "/");
87
- normalized = normalized.replace(/\.(tsx?|jsx?)$/i, "");
88
- if (normalized.endsWith("/index")) {
89
- normalized = normalized.slice(0, -"/index".length);
90
- }
91
- return normalized;
117
+ /**
118
+ * Merges two declared module maps, combining their allowable specific scopes.
119
+ *
120
+ * @param a - First map of declared modules.
121
+ * @param b - Second map of declared modules to merge into the first.
122
+ * @returns A unified map of both declarations.
123
+ */
124
+ export function mergeDeclaredModulesMap(a, b) {
125
+ const result = new Map(a);
126
+ for (const [pkg, imports] of b.entries()) {
127
+ const existing = result.get(pkg);
128
+ if (existing === '*')
129
+ continue;
130
+ if (imports === '*') {
131
+ result.set(pkg, '*');
132
+ continue;
133
+ }
134
+ if (!existing) {
135
+ result.set(pkg, imports);
136
+ }
137
+ else {
138
+ for (const name of imports) {
139
+ existing.add(name);
140
+ }
141
+ }
142
+ }
143
+ return result;
144
+ }
145
+ export function normalizeRequestedExportsKey(pathname) {
146
+ let normalized = pathname.replace(/\\/g, '/');
147
+ normalized = normalized.replace(/\.(tsx?|jsx?)$/i, '');
148
+ if (normalized.endsWith('/index')) {
149
+ normalized = normalized.slice(0, -'/index'.length);
150
+ }
151
+ return normalized;
92
152
  }
93
- function resolveRequestedExportsKey(importer, specifier) {
94
- if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
95
- return void 0;
96
- }
97
- const resolved = specifier.startsWith("/") ? specifier : resolve(dirname(importer), specifier);
98
- return normalizeRequestedExportsKey(resolved);
153
+ /**
154
+ * Resolves a local import specifier into a requested-export registry key.
155
+ *
156
+ * Bare package specifiers and project aliases are intentionally ignored because
157
+ * requested-export propagation is only used for cross-file local reachability.
158
+ *
159
+ * @param importer - Absolute path of the importing module.
160
+ * @param specifier - Raw import or re-export specifier.
161
+ * @returns Registry key for a local dependency, or `undefined` when not applicable.
162
+ */
163
+ export function resolveRequestedExportsKey(importer, specifier) {
164
+ if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
165
+ return undefined;
166
+ }
167
+ const resolved = specifier.startsWith('/') ? specifier : resolve(dirname(importer), specifier);
168
+ return normalizeRequestedExportsKey(resolved);
99
169
  }
100
- function mergeRequestedExportRules(registry, moduleKey, rules) {
101
- const existing = registry.get(moduleKey);
102
- if (existing === "*") return;
103
- if (rules === "*") {
104
- registry.set(moduleKey, "*");
105
- return;
106
- }
107
- if (!existing) {
108
- registry.set(moduleKey, new Set(rules));
109
- return;
110
- }
111
- for (const rule of rules) {
112
- existing.add(rule);
113
- }
170
+ /**
171
+ * Merges newly discovered requested-export rules into the local propagation registry.
172
+ *
173
+ * Once a module is promoted to `'*'`, it stays fully reachable for the remainder
174
+ * of the transform pass.
175
+ *
176
+ * @param registry - Cross-module requested-export registry.
177
+ * @param moduleKey - Normalized local module key.
178
+ * @param rules - Newly observed reachable export rules for the module.
179
+ */
180
+ export function mergeRequestedExportRules(registry, moduleKey, rules) {
181
+ const existing = registry.get(moduleKey);
182
+ if (existing === '*')
183
+ return;
184
+ if (rules === '*') {
185
+ registry.set(moduleKey, '*');
186
+ return;
187
+ }
188
+ if (!existing) {
189
+ registry.set(moduleKey, new Set(rules));
190
+ return;
191
+ }
192
+ for (const rule of rules) {
193
+ existing.add(rule);
194
+ }
114
195
  }
115
196
  function cloneRequestedExportRules(rules) {
116
- return rules === "*" ? rules : new Set(rules);
197
+ return rules === '*' ? rules : new Set(rules);
117
198
  }
118
- function snapshotRegistry(registry) {
119
- const out = /* @__PURE__ */ new Map();
120
- for (const [key, rules] of registry) {
121
- out.set(key, cloneRequestedExportRules(rules));
122
- }
123
- return out;
199
+ export function snapshotRegistry(registry) {
200
+ const out = new Map();
201
+ for (const [key, rules] of registry) {
202
+ out.set(key, cloneRequestedExportRules(rules));
203
+ }
204
+ return out;
124
205
  }
125
- function diffRequestedExportRules(before, after) {
126
- if (!before) {
127
- return cloneRequestedExportRules(after);
128
- }
129
- if (before === "*") {
130
- return void 0;
131
- }
132
- if (after === "*") {
133
- return "*";
134
- }
135
- const addedRules = /* @__PURE__ */ new Set();
136
- for (const rule of after) {
137
- if (!before.has(rule)) {
138
- addedRules.add(rule);
139
- }
140
- }
141
- return addedRules.size > 0 ? addedRules : void 0;
206
+ export function diffRequestedExportRules(before, after) {
207
+ if (!before) {
208
+ return cloneRequestedExportRules(after);
209
+ }
210
+ if (before === '*') {
211
+ return undefined;
212
+ }
213
+ if (after === '*') {
214
+ return '*';
215
+ }
216
+ const addedRules = new Set();
217
+ for (const rule of after) {
218
+ if (!before.has(rule)) {
219
+ addedRules.add(rule);
220
+ }
221
+ }
222
+ return addedRules.size > 0 ? addedRules : undefined;
142
223
  }
143
- export {
144
- diffRequestedExportRules,
145
- isBareSpecifier,
146
- isProjectAliasSpecifier,
147
- isServerOnlySpecifier,
148
- mergeDeclaredModulesMap,
149
- mergeRequestedExportRules,
150
- normalizeRequestedExportsKey,
151
- parseDeclaredModules,
152
- resolveRequestedExportsKey,
153
- snapshotRegistry,
154
- toModuleBaseSpecifier
155
- };
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Router adapter interface for React integration.
3
+ * Allows pluggable SPA routers to be used with the React plugin.
4
+ * @module
5
+ */
6
+ export {};
@@ -0,0 +1,17 @@
1
+ import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
2
+ import type { DevTransformBundleContributor } from '@ecopages/core/dev/transform-server';
3
+ import type { ReactHmrStrategy } from '../hmr/hmr-strategy.js';
4
+ export type ReactDevTransformContributorOptions = {
5
+ strategy: ReactHmrStrategy;
6
+ };
7
+ /**
8
+ * Supplies React module plugins for the core dev transform bundler.
9
+ */
10
+ export declare class ReactDevTransformContributor implements DevTransformBundleContributor {
11
+ private readonly strategy;
12
+ constructor(options: ReactDevTransformContributorOptions);
13
+ ownsModule(sourcePath: string): boolean;
14
+ getModulePlugins(sourcePath: string): Promise<readonly EcoBuildPlugin[]>;
15
+ getRuntimeSpecifierMap(): ReadonlyMap<string, string>;
16
+ getVendorBundlePlugins(): Promise<readonly EcoBuildPlugin[]>;
17
+ }
@@ -0,0 +1,22 @@
1
+ import { getBrowserRuntimeSpecifierMap } from '@ecopages/core/build/browser-runtime-manifest';
2
+ /**
3
+ * Supplies React module plugins for the core dev transform bundler.
4
+ */
5
+ export class ReactDevTransformContributor {
6
+ strategy;
7
+ constructor(options) {
8
+ this.strategy = options.strategy;
9
+ }
10
+ ownsModule(sourcePath) {
11
+ return this.strategy.ownsDevTransformEntrypoint(sourcePath);
12
+ }
13
+ async getModulePlugins(sourcePath) {
14
+ return this.strategy.createDevTransformPlugins(sourcePath);
15
+ }
16
+ getRuntimeSpecifierMap() {
17
+ return getBrowserRuntimeSpecifierMap(this.strategy.getRuntimeManifest());
18
+ }
19
+ async getVendorBundlePlugins() {
20
+ return this.strategy.getVendorBundlePlugins();
21
+ }
22
+ }
@@ -1,9 +1,26 @@
1
- const HMR_MARKER = "/* [ecopages] react-hmr */";
2
- function hasHmrMarker(code) {
3
- return code.includes(HMR_MARKER);
1
+ /**
2
+ * HMR script utilities for React components.
3
+ * @module
4
+ */
5
+ /** Marker comment to identify already-processed HMR code */
6
+ const HMR_MARKER = '/* [ecopages] react-hmr */';
7
+ /**
8
+ * Checks if code has already been processed with HMR marker.
9
+ * @param code - The bundled code to check
10
+ * @returns True if the code already contains the HMR marker
11
+ */
12
+ export function hasHmrMarker(code) {
13
+ return code.includes(HMR_MARKER);
4
14
  }
5
- function injectHmrHandler(code) {
6
- return `${HMR_MARKER}
15
+ /**
16
+ * Injects HMR acceptance handler into bundled code.
17
+ * When a module with React exports changes, it triggers a full invalidation
18
+ * to ensure the parent module re-imports and re-renders with the updated component.
19
+ * @param code - The bundled code to wrap
20
+ * @returns Code with HMR handler injected
21
+ */
22
+ export function injectHmrHandler(code) {
23
+ return `${HMR_MARKER}
7
24
  ${code}
8
25
  if (import.meta.hot) {
9
26
  import.meta.hot.accept((newModule) => {
@@ -25,7 +42,3 @@ if (import.meta.hot) {
25
42
  }
26
43
  `;
27
44
  }
28
- export {
29
- hasHmrMarker,
30
- injectHmrHandler
31
- };