@ecopages/react 0.2.1-beta.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/README.md +164 -28
  2. package/package.json +67 -30
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.js +38 -0
  6. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  7. package/src/bundling/bootstrap-package-paths.js +5 -0
  8. package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +29 -11
  9. package/src/bundling/bundle.js +130 -0
  10. package/src/bundling/runtime-alias-map.d.ts +12 -0
  11. package/src/bundling/runtime-alias-map.js +110 -0
  12. package/src/bundling/runtime-bundle.d.ts +70 -0
  13. package/src/bundling/runtime-bundle.js +233 -0
  14. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  15. package/src/bundling/runtime-interop-plugin.js +32 -0
  16. package/src/bundling/runtime-mode.d.ts +1 -0
  17. package/src/bundling/runtime-mode.js +10 -0
  18. package/src/bundling/runtime-modules.d.ts +21 -0
  19. package/src/bundling/runtime-modules.js +28 -0
  20. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  21. package/src/client-graph/ast-transform-eco-page.js +71 -0
  22. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  23. package/src/client-graph/ast-transform-import-edits.js +75 -0
  24. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  25. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  26. package/src/client-graph/ast-transform.d.ts +12 -0
  27. package/src/client-graph/ast-transform.js +91 -0
  28. package/src/client-graph/ast-walk.d.ts +10 -0
  29. package/src/client-graph/ast-walk.js +26 -0
  30. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  31. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  32. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  33. package/src/client-graph/boundary-plugin-transform.js +31 -0
  34. package/src/client-graph/boundary-plugin.d.ts +23 -0
  35. package/src/client-graph/boundary-plugin.js +177 -0
  36. package/src/client-graph/component-config-traversal.js +77 -0
  37. package/src/client-graph/declared-modules.js +69 -0
  38. package/src/client-graph/module-classification.d.ts +3 -0
  39. package/src/client-graph/module-classification.js +43 -0
  40. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  41. package/src/client-graph/reachability-analyzer.js +55 -0
  42. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  43. package/src/client-graph/reachability-client-roots.js +59 -0
  44. package/src/client-graph/reachability-export-names.d.ts +5 -0
  45. package/src/client-graph/reachability-export-names.js +34 -0
  46. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  47. package/src/client-graph/reachability-fallback-roots.js +71 -0
  48. package/src/client-graph/reachability-preload.d.ts +10 -0
  49. package/src/client-graph/reachability-preload.js +30 -0
  50. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  51. package/src/client-graph/reachability-top-level-index.js +93 -0
  52. package/src/client-graph/reachability-traverse.d.ts +7 -0
  53. package/src/client-graph/reachability-traverse.js +201 -0
  54. package/src/client-graph/specifier-classification.d.ts +74 -0
  55. package/src/client-graph/specifier-classification.js +191 -0
  56. package/src/content/collection-component-cache.d.ts +25 -0
  57. package/src/content/collection-component-cache.js +62 -0
  58. package/src/contracts/router-adapter.js +6 -0
  59. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  60. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  61. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  62. package/src/hmr/hmr-strategy-process.js +83 -0
  63. package/src/hmr/hmr-strategy.d.ts +67 -0
  64. package/src/hmr/hmr-strategy.js +306 -0
  65. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
  66. package/src/hmr/page-metadata-cache.js +44 -0
  67. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  68. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  69. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  70. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  71. package/src/hydration/bootstrap-imports.d.ts +25 -0
  72. package/src/hydration/bootstrap-imports.js +33 -0
  73. package/src/hydration/browser/island-hydration.d.ts +82 -0
  74. package/src/hydration/browser/island-hydration.js +251 -0
  75. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  76. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  77. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  78. package/src/hydration/browser/page-hydration-module.js +17 -0
  79. package/src/hydration/browser/page-hydration.d.ts +54 -0
  80. package/src/hydration/browser/page-hydration.js +177 -0
  81. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  82. package/src/hydration/hydration-asset.d.ts +127 -0
  83. package/src/hydration/hydration-asset.js +379 -0
  84. package/src/hydration/hydration-lifecycle.test.browser.d.ts +1 -0
  85. package/src/hydration/hydration-lifecycle.test.browser.js +461 -0
  86. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  87. package/src/hydration/hydration-page-entry-source.js +87 -0
  88. package/src/hydration/hydration-script-compiler.d.ts +48 -0
  89. package/src/hydration/hydration-script-compiler.js +213 -0
  90. package/src/hydration/page-data-manifest.d.ts +58 -0
  91. package/src/hydration/page-data-manifest.js +97 -0
  92. package/src/hydration/page-data-reader.d.ts +17 -0
  93. package/src/hydration/page-data-reader.js +31 -0
  94. package/src/hydration/page-payload.d.ts +68 -0
  95. package/src/hydration/page-payload.js +106 -0
  96. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  97. package/src/hydration/serialize-page-data-script.js +30 -0
  98. package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +9 -8
  99. package/src/mdx/mdx-config-dependency.js +107 -0
  100. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  101. package/src/mdx/mdx-loader-plugin.js +11 -0
  102. package/src/page/page-module.d.ts +46 -0
  103. package/src/page/page-module.js +74 -0
  104. package/src/plugin/react.constants.js +1 -0
  105. package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +21 -27
  106. package/src/plugin/react.plugin.js +210 -0
  107. package/src/plugin/react.types.d.ts +106 -0
  108. package/src/plugin/react.types.js +1 -0
  109. package/src/render/component-ownership.d.ts +49 -0
  110. package/src/render/component-ownership.js +47 -0
  111. package/src/render/component-ssr.d.ts +59 -0
  112. package/src/render/component-ssr.js +76 -0
  113. package/src/render/eco-embed.js +9 -0
  114. package/src/render/errors.d.ts +16 -0
  115. package/src/render/errors.js +23 -0
  116. package/src/render/html-boundary.js +59 -0
  117. package/src/render/layout-compose.d.ts +66 -0
  118. package/src/render/layout-compose.js +134 -0
  119. package/src/render/react-renderer.d.ts +114 -0
  120. package/src/render/react-renderer.js +490 -0
  121. package/src/render/react-runtime.d.ts +13 -0
  122. package/src/render/react-runtime.js +26 -0
  123. package/src/render/unified-layout-composition.d.ts +22 -0
  124. package/src/render/unified-layout-composition.js +31 -0
  125. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
  126. package/src/eco-embed.js +0 -11
  127. package/src/react-hmr-strategy.d.ts +0 -230
  128. package/src/react-hmr-strategy.js +0 -657
  129. package/src/react-renderer.d.ts +0 -233
  130. package/src/react-renderer.js +0 -622
  131. package/src/react.constants.js +0 -4
  132. package/src/react.plugin.js +0 -205
  133. package/src/react.types.d.ts +0 -88
  134. package/src/react.types.js +0 -0
  135. package/src/router-adapter.js +0 -0
  136. package/src/services/pages-index.d.ts +0 -64
  137. package/src/services/pages-index.js +0 -73
  138. package/src/services/react-bundle.service.js +0 -86
  139. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  140. package/src/services/react-hydration-asset.service.d.ts +0 -84
  141. package/src/services/react-hydration-asset.service.js +0 -217
  142. package/src/services/react-mdx-config-dependency.service.js +0 -122
  143. package/src/services/react-page-module.service.d.ts +0 -88
  144. package/src/services/react-page-module.service.js +0 -166
  145. package/src/services/react-page-payload.service.d.ts +0 -46
  146. package/src/services/react-page-payload.service.js +0 -67
  147. package/src/services/react-runtime-bundle.service.d.ts +0 -45
  148. package/src/services/react-runtime-bundle.service.js +0 -186
  149. package/src/utils/client-graph-boundary-cache.d.ts +0 -108
  150. package/src/utils/client-graph-boundary-cache.js +0 -116
  151. package/src/utils/client-graph-boundary-plugin.d.ts +0 -51
  152. package/src/utils/client-graph-boundary-plugin.js +0 -552
  153. package/src/utils/client-only.js +0 -19
  154. package/src/utils/component-config-traversal.js +0 -54
  155. package/src/utils/declared-modules.js +0 -47
  156. package/src/utils/dynamic.js +0 -12
  157. package/src/utils/dynamic.test.browser.js +0 -33
  158. package/src/utils/hmr-scripts.d.ts +0 -18
  159. package/src/utils/hmr-scripts.js +0 -31
  160. package/src/utils/html-boundary.js +0 -55
  161. package/src/utils/hydration-scripts.d.ts +0 -92
  162. package/src/utils/hydration-scripts.js +0 -358
  163. package/src/utils/hydration-scripts.test.browser.js +0 -198
  164. package/src/utils/reachability-analyzer.d.ts +0 -66
  165. package/src/utils/reachability-analyzer.js +0 -339
  166. package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
  167. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  168. package/src/utils/react-mdx-loader-plugin.js +0 -45
  169. package/src/utils/react-runtime-alias-map.d.ts +0 -8
  170. package/src/utils/react-runtime-alias-map.js +0 -90
  171. /package/src/{utils → app}/client-only.d.ts +0 -0
  172. /package/src/{utils → app}/dynamic.d.ts +0 -0
  173. /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
  174. /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
  175. /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
  176. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  177. /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
  178. /package/src/{utils/hydration-scripts.test.browser.d.ts → hydration/compiled-page-hydration-options.js} +0 -0
  179. /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
  180. /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
  181. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,30 @@
1
+ import { parseModuleSource } from '@ecopages/core/build';
2
+ export function isPreloadExportStatement(statement) {
3
+ const declaration = statement.declaration;
4
+ if (declaration?.type === 'FunctionDeclaration' || declaration?.type === 'ClassDeclaration') {
5
+ return declaration.id?.type === 'Identifier' && declaration.id.name === 'preload';
6
+ }
7
+ if (declaration?.type === 'VariableDeclaration') {
8
+ return (declaration.declarations?.some((declarator) => declarator.id.type === 'Identifier' && declarator.id.name === 'preload') ?? false);
9
+ }
10
+ return statement.specifiers.some((specifier) => {
11
+ const exported = specifier.exported;
12
+ return exported.type === 'Identifier' ? exported.name === 'preload' : exported.value === 'preload';
13
+ });
14
+ }
15
+ /**
16
+ * Returns whether a module exports a named `preload` binding.
17
+ *
18
+ * @remarks
19
+ * Hydration entries only wire `preload` when this is true, so Pages without
20
+ * that export do not produce a missing-named-import warning.
21
+ */
22
+ export function hasPagePreloadExport(source, filename) {
23
+ try {
24
+ const { program } = parseModuleSource(filename, source);
25
+ return program.body.some((statement) => statement.type === 'ExportNamedDeclaration' && isPreloadExportStatement(statement));
26
+ }
27
+ catch {
28
+ return false;
29
+ }
30
+ }
@@ -0,0 +1,14 @@
1
+ import type { ParseResult } from 'oxc-parser';
2
+ import { type ClientRootScanState } from './reachability-client-roots.js';
3
+ export type TopLevelImportEntry = {
4
+ node: unknown;
5
+ specifier: string;
6
+ bindings: Map<string, string>;
7
+ isSideEffect: boolean;
8
+ };
9
+ export type TopLevelIndex = {
10
+ topLevelImports: TopLevelImportEntry[];
11
+ topLevelDeclarations: Map<string, unknown>;
12
+ clientRootState: ClientRootScanState;
13
+ };
14
+ export declare function buildTopLevelIndex(program: ParseResult['program']): TopLevelIndex;
@@ -0,0 +1,93 @@
1
+ import { checkPotentialClientRoot, createClientRootScanState, } from './reachability-client-roots.js';
2
+ import { isPreloadExportStatement } from './reachability-preload.js';
3
+ function indexImportDeclaration(statement, topLevelImports) {
4
+ if (statement.importKind === 'type') {
5
+ return;
6
+ }
7
+ const specifier = statement.source.value;
8
+ const bindings = new Map();
9
+ if (!statement.specifiers || statement.specifiers.length === 0) {
10
+ topLevelImports.push({ node: statement, specifier, bindings, isSideEffect: true });
11
+ return;
12
+ }
13
+ for (const spec of statement.specifiers) {
14
+ if (spec.type === 'ImportDefaultSpecifier') {
15
+ bindings.set(spec.local.name, 'default');
16
+ }
17
+ else if (spec.type === 'ImportNamespaceSpecifier') {
18
+ bindings.set(spec.local.name, '*');
19
+ }
20
+ else if (spec.type === 'ImportSpecifier') {
21
+ const importedName = spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
22
+ bindings.set(spec.local.name, importedName);
23
+ }
24
+ }
25
+ topLevelImports.push({ node: statement, specifier, bindings, isSideEffect: false });
26
+ }
27
+ function indexExportNamedDeclaration(statement, index) {
28
+ const decl = statement.declaration;
29
+ if (isPreloadExportStatement(statement)) {
30
+ index.clientRootState.pagePreloadRoots.push(statement);
31
+ }
32
+ if (!decl) {
33
+ return;
34
+ }
35
+ if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
36
+ if (decl.id?.type === 'Identifier') {
37
+ index.topLevelDeclarations.set(decl.id.name, statement);
38
+ }
39
+ return;
40
+ }
41
+ if (decl.type === 'VariableDeclaration') {
42
+ for (const v of decl.declarations) {
43
+ if (v.id.type === 'Identifier') {
44
+ index.topLevelDeclarations.set(v.id.name, statement);
45
+ checkPotentialClientRoot(v.init, index.clientRootState);
46
+ }
47
+ }
48
+ }
49
+ }
50
+ export function buildTopLevelIndex(program) {
51
+ const index = {
52
+ topLevelImports: [],
53
+ topLevelDeclarations: new Map(),
54
+ clientRootState: createClientRootScanState(),
55
+ };
56
+ for (const statement of program.body) {
57
+ if (statement.type === 'ImportDeclaration') {
58
+ indexImportDeclaration(statement, index.topLevelImports);
59
+ continue;
60
+ }
61
+ if (statement.type === 'VariableDeclaration') {
62
+ for (const decl of statement.declarations) {
63
+ if (decl.id.type === 'Identifier') {
64
+ index.topLevelDeclarations.set(decl.id.name, statement);
65
+ checkPotentialClientRoot(decl.init, index.clientRootState);
66
+ }
67
+ }
68
+ continue;
69
+ }
70
+ if (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') {
71
+ if (statement.id?.type === 'Identifier') {
72
+ index.topLevelDeclarations.set(statement.id.name, statement);
73
+ }
74
+ continue;
75
+ }
76
+ if (statement.type === 'ExportNamedDeclaration') {
77
+ indexExportNamedDeclaration(statement, index);
78
+ continue;
79
+ }
80
+ if (statement.type === 'ExportDefaultDeclaration') {
81
+ checkPotentialClientRoot(statement.declaration, index.clientRootState);
82
+ continue;
83
+ }
84
+ if (statement.type === 'ExpressionStatement') {
85
+ checkPotentialClientRoot(statement.expression, index.clientRootState);
86
+ continue;
87
+ }
88
+ if (statement.type === 'ExportAllDeclaration' && statement.source) {
89
+ index.clientRootState.potentialClientRoots.push(statement);
90
+ }
91
+ }
92
+ return index;
93
+ }
@@ -0,0 +1,7 @@
1
+ import { type ExplicitlyRequestedExports } from './reachability-export-names.js';
2
+ import type { TopLevelImportEntry } from './reachability-top-level-index.js';
3
+ export type ReachabilityTraversalResult = {
4
+ reachableImports: Map<string, Set<string> | '*'>;
5
+ reachableDeclarations: Set<unknown>;
6
+ };
7
+ export declare function runReachabilityTraversal(roots: unknown[], topLevelImports: TopLevelImportEntry[], topLevelDeclarations: Map<string, unknown>, explicitlyRequestedExports?: ExplicitlyRequestedExports): ReachabilityTraversalResult;
@@ -0,0 +1,201 @@
1
+ import { getExportedName, getLocalExportName, getReexportedImportName, isExplicitlyRequestedExport, } from './reachability-export-names.js';
2
+ function markImportReachable(reachableImports, specifier, importedName) {
3
+ let current = reachableImports.get(specifier);
4
+ if (current === '*')
5
+ return;
6
+ if (importedName === '*') {
7
+ reachableImports.set(specifier, '*');
8
+ return;
9
+ }
10
+ if (!current) {
11
+ current = new Set();
12
+ reachableImports.set(specifier, current);
13
+ }
14
+ current.add(importedName);
15
+ }
16
+ function createTraversalContext(topLevelImports, topLevelDeclarations, explicitlyRequestedExports) {
17
+ const reachableImports = new Map();
18
+ const reachableDeclarations = new Set();
19
+ const queue = [];
20
+ const visitedNodes = new Set();
21
+ function checkIdentifier(name) {
22
+ if (topLevelDeclarations.has(name)) {
23
+ const declNode = topLevelDeclarations.get(name);
24
+ if (!reachableDeclarations.has(declNode)) {
25
+ reachableDeclarations.add(declNode);
26
+ queue.push(declNode);
27
+ }
28
+ }
29
+ for (const imp of topLevelImports) {
30
+ if (imp.bindings.has(name)) {
31
+ markImportReachable(reachableImports, imp.specifier, imp.bindings.get(name));
32
+ }
33
+ }
34
+ }
35
+ return {
36
+ reachableImports,
37
+ reachableDeclarations,
38
+ queue,
39
+ visitedNodes,
40
+ checkIdentifier,
41
+ explicitlyRequestedExports,
42
+ };
43
+ }
44
+ function visitExportAll(node, ctx) {
45
+ if (typeof node.source?.value !== 'string')
46
+ return false;
47
+ markImportReachable(ctx.reachableImports, node.source.value, '*');
48
+ return true;
49
+ }
50
+ function visitExportNamed(node, ctx, localScope) {
51
+ if (typeof node.source?.value === 'string') {
52
+ for (const specifier of node.specifiers ?? []) {
53
+ const importedName = getReexportedImportName(specifier);
54
+ if (importedName) {
55
+ markImportReachable(ctx.reachableImports, node.source.value, importedName);
56
+ }
57
+ }
58
+ return true;
59
+ }
60
+ if (node.source || !ctx.explicitlyRequestedExports || !node.specifiers?.length) {
61
+ return false;
62
+ }
63
+ for (const specifier of node.specifiers) {
64
+ const exportedName = getExportedName(specifier);
65
+ if (!exportedName || !isExplicitlyRequestedExport(exportedName, ctx.explicitlyRequestedExports)) {
66
+ continue;
67
+ }
68
+ const localName = getLocalExportName(specifier);
69
+ if (localName && !localScope.has(localName)) {
70
+ ctx.checkIdentifier(localName);
71
+ }
72
+ }
73
+ return true;
74
+ }
75
+ function visitIdentifier(node, ctx, localScope) {
76
+ if (!localScope.has(node.name)) {
77
+ ctx.checkIdentifier(node.name);
78
+ }
79
+ return false;
80
+ }
81
+ function visitJsxIdentifier(node, ctx, localScope) {
82
+ if (/^[A-Z]/.test(node.name) && !localScope.has(node.name)) {
83
+ ctx.checkIdentifier(node.name);
84
+ }
85
+ return false;
86
+ }
87
+ function visitMemberExpression(node, ctx, localScope) {
88
+ traverseNode(node.object, ctx, localScope);
89
+ if (node.computed) {
90
+ traverseNode(node.property, ctx, localScope);
91
+ }
92
+ return true;
93
+ }
94
+ function visitProperty(node, ctx, localScope) {
95
+ if (node.computed)
96
+ traverseNode(node.key, ctx, localScope);
97
+ traverseNode(node.value, ctx, localScope);
98
+ return true;
99
+ }
100
+ function visitJsxElement(node, ctx, localScope) {
101
+ traverseNode(node.name, ctx, localScope);
102
+ if (node.attributes) {
103
+ for (const attr of node.attributes)
104
+ traverseNode(attr, ctx, localScope);
105
+ }
106
+ return true;
107
+ }
108
+ function visitJsxMemberExpression(node, ctx, localScope) {
109
+ traverseNode(node.object, ctx, localScope);
110
+ return true;
111
+ }
112
+ function visitCallExpression(node, ctx) {
113
+ if (node.callee?.type !== 'Identifier') {
114
+ return false;
115
+ }
116
+ if (node.callee.name === 'dynamic') {
117
+ const arg = node.arguments[0];
118
+ if (arg && (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression')) {
119
+ const body = arg.body;
120
+ if (body.type === 'ImportExpression' && body.source.type === 'Literal') {
121
+ markImportReachable(ctx.reachableImports, body.source.value, '*');
122
+ }
123
+ }
124
+ return false;
125
+ }
126
+ if (node.callee.name === 'require') {
127
+ const arg = node.arguments?.[0];
128
+ if (arg && (arg.type === 'StringLiteral' || arg.type === 'Literal') && typeof arg.value === 'string') {
129
+ markImportReachable(ctx.reachableImports, arg.value, '*');
130
+ }
131
+ }
132
+ return false;
133
+ }
134
+ function visitImportExpression(node, ctx) {
135
+ if (node.source.type === 'Literal') {
136
+ markImportReachable(ctx.reachableImports, node.source.value, '*');
137
+ }
138
+ return false;
139
+ }
140
+ function visitFunctionNode(node, ctx, localScope) {
141
+ const newScope = new Set(localScope);
142
+ if (node.id?.type === 'Identifier')
143
+ newScope.add(node.id.name);
144
+ if (node.params?.items) {
145
+ for (const p of node.params.items) {
146
+ if (p.pattern?.type === 'Identifier') {
147
+ newScope.add(p.pattern.name);
148
+ }
149
+ }
150
+ }
151
+ traverseNode(node.body, ctx, newScope);
152
+ return true;
153
+ }
154
+ const NODE_VISITORS = new Map([
155
+ ['ExportAllDeclaration', visitExportAll],
156
+ ['ExportNamedDeclaration', visitExportNamed],
157
+ ['Identifier', visitIdentifier],
158
+ ['JSXIdentifier', visitJsxIdentifier],
159
+ ['MemberExpression', visitMemberExpression],
160
+ ['Property', visitProperty],
161
+ ['JSXOpeningElement', visitJsxElement],
162
+ ['JSXClosingElement', visitJsxElement],
163
+ ['JSXMemberExpression', visitJsxMemberExpression],
164
+ ['CallExpression', visitCallExpression],
165
+ ['ImportExpression', visitImportExpression],
166
+ ['ArrowFunctionExpression', visitFunctionNode],
167
+ ['FunctionExpression', visitFunctionNode],
168
+ ['FunctionDeclaration', visitFunctionNode],
169
+ ]);
170
+ function traverseNode(node, ctx, localScope) {
171
+ if (!node || typeof node !== 'object')
172
+ return;
173
+ if (ctx.visitedNodes.has(node))
174
+ return;
175
+ ctx.visitedNodes.add(node);
176
+ if (Array.isArray(node)) {
177
+ for (const child of node)
178
+ traverseNode(child, ctx, localScope);
179
+ return;
180
+ }
181
+ const visitor = NODE_VISITORS.get(node.type);
182
+ if (visitor?.(node, ctx, localScope))
183
+ return;
184
+ for (const key in node) {
185
+ if (key !== 'type' && key !== 'start' && key !== 'end') {
186
+ traverseNode(node[key], ctx, localScope);
187
+ }
188
+ }
189
+ }
190
+ export function runReachabilityTraversal(roots, topLevelImports, topLevelDeclarations, explicitlyRequestedExports) {
191
+ const ctx = createTraversalContext(topLevelImports, topLevelDeclarations, explicitlyRequestedExports);
192
+ ctx.queue.push(...roots);
193
+ while (ctx.queue.length > 0) {
194
+ const root = ctx.queue.shift();
195
+ traverseNode(root, ctx, new Set());
196
+ }
197
+ return {
198
+ reachableImports: ctx.reachableImports,
199
+ reachableDeclarations: ctx.reachableDeclarations,
200
+ };
201
+ }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Specifier classification and requested-export registry helpers for the client graph boundary.
3
+ */
4
+ export type RequestedExportRules = Set<string> | '*';
5
+ export declare function isBareSpecifier(specifier: string): boolean;
6
+ export declare function isProjectAliasSpecifier(specifier: string, projectRoot?: string): boolean;
7
+ /**
8
+ * Determines whether a specifier should be treated as server-only.
9
+ *
10
+ * This covers Node built-ins, content collection `/server` virtual modules,
11
+ * and local module conventions such as `.server.ts` and extensionless imports
12
+ * that resolve to `.server.*` files.
13
+ *
14
+ * @param specifier - Raw import specifier from the module source.
15
+ * @returns True when the import must never become client-reachable.
16
+ */
17
+ export declare function isServerOnlySpecifier(specifier: string): boolean;
18
+ /**
19
+ * Strips down a deep path module specifier to its foundational root package name.
20
+ *
21
+ * When checking against the "allowed modules" whitelist, a component might import something deeply
22
+ * nested like `lodash/fp/map` or `@myorg/ui/button`. However, the user configuration only whitelists
23
+ * the root `lodash` or `@myorg/ui` package. This normalizer ensures we are comparing apples to apples
24
+ * by extracting the base package scope before checking the authorization list.
25
+ *
26
+ * @example
27
+ * toModuleBaseSpecifier('@scope/package/deep/file') -> '@scope/package'
28
+ * toModuleBaseSpecifier('lodash/cloneDeep') -> 'lodash'
29
+ * toModuleBaseSpecifier('node:fs') -> 'node:fs'
30
+ *
31
+ * @param specifier - The raw import specifier from the code.
32
+ * @returns The root package name, preserving scoped npm organizations.
33
+ */
34
+ export declare function toModuleBaseSpecifier(specifier: string): string;
35
+ /**
36
+ * Parses the grammar syntax of declared modules.
37
+ * Handles patterns like `@pkg/name` and `@pkg/name{namedImport,anotherImport}`
38
+ * returning a map of base packages to their explicitly allowed specifiers.
39
+ *
40
+ * @param moduleDeclarations - A list of module declaration strings.
41
+ * @returns A structured map of allowed packages and their named exports.
42
+ */
43
+ export declare function parseDeclaredModules(moduleDeclarations: readonly string[] | undefined): Map<string, Set<string> | '*'>;
44
+ /**
45
+ * Merges two declared module maps, combining their allowable specific scopes.
46
+ *
47
+ * @param a - First map of declared modules.
48
+ * @param b - Second map of declared modules to merge into the first.
49
+ * @returns A unified map of both declarations.
50
+ */
51
+ export declare function mergeDeclaredModulesMap(a: Map<string, Set<string> | '*'>, b: Map<string, Set<string> | '*'>): Map<string, Set<string> | '*'>;
52
+ export declare function normalizeRequestedExportsKey(pathname: string): string;
53
+ /**
54
+ * Resolves a local import specifier into a requested-export registry key.
55
+ *
56
+ * Bare package specifiers and project aliases are intentionally ignored because
57
+ * requested-export propagation is only used for cross-file local reachability.
58
+ *
59
+ * @param importer - Absolute path of the importing module.
60
+ * @param specifier - Raw import or re-export specifier.
61
+ * @returns Registry key for a local dependency, or `undefined` when not applicable.
62
+ */
63
+ export declare function resolveRequestedExportsKey(importer: string, specifier: string): string | undefined;
64
+ /**
65
+ * Merges newly discovered requested-export rules into the local propagation registry.
66
+ *
67
+ * Once a module is promoted to `'*'`, it stays fully reachable for the remainder
68
+ * of the transform pass.
69
+ *
70
+ * @param registry - Cross-module requested-export registry.
71
+ * @param moduleKey - Normalized local module key.
72
+ * @param rules - Newly observed reachable export rules for the module.
73
+ */
74
+ export declare function mergeRequestedExportRules(registry: Map<string, RequestedExportRules>, moduleKey: string, rules: Set<string> | '*'): void;
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Specifier classification and requested-export registry helpers for the client graph boundary.
3
+ */
4
+ import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from '@ecopages/core/build';
5
+ import { toPackageRootSpecifier } from '@ecopages/core/build';
6
+ import { isContentServerVirtualModule } from '@ecopages/core/build';
7
+ import { isServerOnlyModuleSpecifier } from '@ecopages/core/build/contracts';
8
+ import { dirname, resolve } from 'node:path';
9
+ export function isBareSpecifier(specifier) {
10
+ if (specifier.startsWith('.'))
11
+ return false;
12
+ if (specifier.startsWith('/'))
13
+ return false;
14
+ if (specifier.includes('://'))
15
+ return false;
16
+ return true;
17
+ }
18
+ export function isProjectAliasSpecifier(specifier, projectRoot) {
19
+ if (specifier.startsWith('ecopages:')) {
20
+ return true;
21
+ }
22
+ if (projectRoot) {
23
+ return matchesTsconfigPathPrefix(specifier, loadTsconfigPathPrefixes(projectRoot));
24
+ }
25
+ return false;
26
+ }
27
+ /**
28
+ * Determines whether a specifier should be treated as server-only.
29
+ *
30
+ * This covers Node built-ins, content collection `/server` virtual modules,
31
+ * and local module conventions such as `.server.ts` and extensionless imports
32
+ * that resolve to `.server.*` files.
33
+ *
34
+ * @param specifier - Raw import specifier from the module source.
35
+ * @returns True when the import must never become client-reachable.
36
+ */
37
+ export function isServerOnlySpecifier(specifier) {
38
+ if (specifier.startsWith('node:'))
39
+ return true;
40
+ if (isContentServerVirtualModule(specifier))
41
+ return true;
42
+ return isServerOnlyModuleSpecifier(specifier);
43
+ }
44
+ /**
45
+ * Strips down a deep path module specifier to its foundational root package name.
46
+ *
47
+ * When checking against the "allowed modules" whitelist, a component might import something deeply
48
+ * nested like `lodash/fp/map` or `@myorg/ui/button`. However, the user configuration only whitelists
49
+ * the root `lodash` or `@myorg/ui` package. This normalizer ensures we are comparing apples to apples
50
+ * by extracting the base package scope before checking the authorization list.
51
+ *
52
+ * @example
53
+ * toModuleBaseSpecifier('@scope/package/deep/file') -> '@scope/package'
54
+ * toModuleBaseSpecifier('lodash/cloneDeep') -> 'lodash'
55
+ * toModuleBaseSpecifier('node:fs') -> 'node:fs'
56
+ *
57
+ * @param specifier - The raw import specifier from the code.
58
+ * @returns The root package name, preserving scoped npm organizations.
59
+ */
60
+ export function toModuleBaseSpecifier(specifier) {
61
+ return toPackageRootSpecifier(specifier);
62
+ }
63
+ /**
64
+ * Parses the grammar syntax of declared modules.
65
+ * Handles patterns like `@pkg/name` and `@pkg/name{namedImport,anotherImport}`
66
+ * returning a map of base packages to their explicitly allowed specifiers.
67
+ *
68
+ * @param moduleDeclarations - A list of module declaration strings.
69
+ * @returns A structured map of allowed packages and their named exports.
70
+ */
71
+ export function parseDeclaredModules(moduleDeclarations) {
72
+ const map = new Map();
73
+ for (const declaration of moduleDeclarations ?? []) {
74
+ const source = declaration.trim();
75
+ if (source.length === 0)
76
+ continue;
77
+ const openBraceIndex = source.indexOf('{');
78
+ if (openBraceIndex < 0) {
79
+ map.set(toModuleBaseSpecifier(source), '*');
80
+ continue;
81
+ }
82
+ const closeBraceIndex = source.indexOf('}', openBraceIndex);
83
+ const rawPkg = source.slice(0, openBraceIndex).trim();
84
+ if (rawPkg.length === 0)
85
+ continue;
86
+ const pkg = toModuleBaseSpecifier(rawPkg);
87
+ const namedImportsStr = closeBraceIndex > openBraceIndex
88
+ ? source.slice(openBraceIndex + 1, closeBraceIndex)
89
+ : source.slice(openBraceIndex + 1);
90
+ const namedImports = namedImportsStr
91
+ .split(',')
92
+ .map((s) => s.trim())
93
+ .filter(Boolean);
94
+ const existing = map.get(pkg);
95
+ if (existing === '*')
96
+ continue;
97
+ if (!existing) {
98
+ if (namedImports.length === 0) {
99
+ map.set(pkg, '*');
100
+ }
101
+ else {
102
+ map.set(pkg, new Set(namedImports));
103
+ }
104
+ }
105
+ else {
106
+ for (const name of namedImports) {
107
+ existing.add(name);
108
+ }
109
+ }
110
+ }
111
+ return map;
112
+ }
113
+ /**
114
+ * Merges two declared module maps, combining their allowable specific scopes.
115
+ *
116
+ * @param a - First map of declared modules.
117
+ * @param b - Second map of declared modules to merge into the first.
118
+ * @returns A unified map of both declarations.
119
+ */
120
+ export function mergeDeclaredModulesMap(a, b) {
121
+ const result = new Map(a);
122
+ for (const [pkg, imports] of b.entries()) {
123
+ const existing = result.get(pkg);
124
+ if (existing === '*')
125
+ continue;
126
+ if (imports === '*') {
127
+ result.set(pkg, '*');
128
+ continue;
129
+ }
130
+ if (!existing) {
131
+ result.set(pkg, imports);
132
+ }
133
+ else {
134
+ for (const name of imports) {
135
+ existing.add(name);
136
+ }
137
+ }
138
+ }
139
+ return result;
140
+ }
141
+ export function normalizeRequestedExportsKey(pathname) {
142
+ let normalized = pathname.replace(/\\/g, '/');
143
+ normalized = normalized.replace(/\.(tsx?|jsx?)$/i, '');
144
+ if (normalized.endsWith('/index')) {
145
+ normalized = normalized.slice(0, -'/index'.length);
146
+ }
147
+ return normalized;
148
+ }
149
+ /**
150
+ * Resolves a local import specifier into a requested-export registry key.
151
+ *
152
+ * Bare package specifiers and project aliases are intentionally ignored because
153
+ * requested-export propagation is only used for cross-file local reachability.
154
+ *
155
+ * @param importer - Absolute path of the importing module.
156
+ * @param specifier - Raw import or re-export specifier.
157
+ * @returns Registry key for a local dependency, or `undefined` when not applicable.
158
+ */
159
+ export function resolveRequestedExportsKey(importer, specifier) {
160
+ if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
161
+ return undefined;
162
+ }
163
+ const resolved = specifier.startsWith('/') ? specifier : resolve(dirname(importer), specifier);
164
+ return normalizeRequestedExportsKey(resolved);
165
+ }
166
+ /**
167
+ * Merges newly discovered requested-export rules into the local propagation registry.
168
+ *
169
+ * Once a module is promoted to `'*'`, it stays fully reachable for the remainder
170
+ * of the transform pass.
171
+ *
172
+ * @param registry - Cross-module requested-export registry.
173
+ * @param moduleKey - Normalized local module key.
174
+ * @param rules - Newly observed reachable export rules for the module.
175
+ */
176
+ export function mergeRequestedExportRules(registry, moduleKey, rules) {
177
+ const existing = registry.get(moduleKey);
178
+ if (existing === '*')
179
+ return;
180
+ if (rules === '*') {
181
+ registry.set(moduleKey, '*');
182
+ return;
183
+ }
184
+ if (!existing) {
185
+ registry.set(moduleKey, new Set(rules));
186
+ return;
187
+ }
188
+ for (const rule of rules) {
189
+ existing.add(rule);
190
+ }
191
+ }
@@ -0,0 +1,25 @@
1
+ import type { EcoComponent } from '@ecopages/core';
2
+ export type CollectionComponentCache = {
3
+ preload(slug: string): Promise<void>;
4
+ prime(slug: string, component: Promise<EcoComponent<Record<string, unknown>>>): Promise<void>;
5
+ get(slug: string): EcoComponent<Record<string, unknown>>;
6
+ };
7
+ /**
8
+ * Creates the synchronous component lookup required by a Page that preloads
9
+ * collection MDX before SSR, hydration, and client navigation.
10
+ *
11
+ * @remarks
12
+ * `preload()` loads the browser-compiled component and must not run in
13
+ * `staticProps`. A hydratable collection Page primes the cache in `staticProps`
14
+ * with its server component, then exposes a named `preload` export for
15
+ * hydration and client navigation to load the browser component.
16
+ *
17
+ * Completed loads are deliberately refreshed by the next preload. Native
18
+ * module caching keeps that inexpensive while allowing HMR to replace a
19
+ * component before the Page re-renders.
20
+ *
21
+ * `prime()` always stores the provided server component, even when a
22
+ * `preload()` is already in flight. Completions from a superseded load are
23
+ * ignored so they cannot replace the primed entry.
24
+ */
25
+ export declare function createCollectionComponentCache(loadComponent: (slug: string) => Promise<EcoComponent<Record<string, unknown>>>): CollectionComponentCache;