@ecopages/react 0.7.1 → 0.9.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.
package/README.md CHANGED
@@ -136,7 +136,7 @@ The client bundle keeps:
136
136
  The client bundle removes or excludes:
137
137
 
138
138
  - Server-only imports that are not reachable from the hydrated render path.
139
- - Server-only `eco.page(...)` options such as `cache`, `middleware`, `metadata`, `staticProps`, and `staticPaths`.
139
+ - Server-only `eco.page(...)` options such as `cache`, `middleware`, `metadata`, `props`, and `paths`.
140
140
  - Request-time configuration that has no meaning in the browser.
141
141
 
142
142
  Important:
@@ -172,18 +172,18 @@ Consider a page like this:
172
172
  import { authMiddleware } from './auth.server';
173
173
  import { getPost } from './posts.server';
174
174
 
175
- const staticProps = async () => ({ props: { post: await getPost() } });
175
+ const getProps = async () => ({ post: await getPost() });
176
176
 
177
177
  export default eco.page({
178
178
  cache: 'dynamic',
179
179
  middleware: [authMiddleware],
180
180
  requires: ['session'] as const,
181
- staticProps,
181
+ props: getProps,
182
182
  render: () => <div>Dashboard</div>,
183
183
  });
184
184
  ```
185
185
 
186
- If the client transform removed the `auth.server` import but left `middleware: [authMiddleware]` in place, the browser bundle would contain a dangling identifier and throw a `ReferenceError` when it loads. The boundary therefore strips the server-only options, then the `staticProps` helper they alone used, while keeping `render` intact.
186
+ If the client transform removed the `auth.server` import but left `middleware: [authMiddleware]` in place, the browser bundle would contain a dangling identifier and throw a `ReferenceError` when it loads. The boundary therefore strips the server-only options, then the `getProps` helper they alone used, while keeping `render` intact.
187
187
 
188
188
  A stripped import still used by code the browser module needs fails the build with its `file:line:column`:
189
189
 
@@ -191,7 +191,7 @@ A stripped import still used by code the browser module needs fails the build wi
191
191
  [Ecopages Client Graph] 'authMiddleware' (imported from './auth.server') is used at src/widget.tsx:2:22, but that import is server-only and the browser build removes it. ...
192
192
  ```
193
193
 
194
- Move that code into a server-only Page option, into a helper only those options use, or out of the code the browser module reaches.
194
+ Move that code into a server-only Page option, into a helper only those options use, or out of the code the browser module reaches. A server-only import that the render function itself uses fails the build the same way, naming the import, its bindings and the `.server` fix.
195
195
 
196
196
  ### Hydration Contract for `locals`
197
197
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.7.1",
3
+ "version": "0.9.0",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -123,16 +123,16 @@
123
123
  "directory": "packages/integrations/react"
124
124
  },
125
125
  "peerDependencies": {
126
- "@ecopages/core": "0.7.1",
126
+ "@ecopages/core": "0.9.0",
127
127
  "@types/react": "^19",
128
128
  "@types/react-dom": "^19",
129
129
  "react": "^19",
130
130
  "react-dom": "^19"
131
131
  },
132
132
  "dependencies": {
133
- "@ecopages/file-system": "0.7.1",
133
+ "@ecopages/file-system": "0.9.0",
134
134
  "@ecopages/logger": "^0.2.3",
135
- "@ecopages/mdx": "0.7.1",
135
+ "@ecopages/mdx": "0.9.0",
136
136
  "@mdx-js/mdx": "^3.1.1",
137
137
  "oxc-parser": "^0.141.0"
138
138
  }
@@ -31,6 +31,12 @@ export declare function getReactClientGraphAllowSpecifiers(routerAdapter?: React
31
31
  export declare class BundleService {
32
32
  private readonly config;
33
33
  private readonly foreignJsxOverridePlugin;
34
+ /**
35
+ * @remarks
36
+ * One instance for every entry: its options do not depend on the entry, and core merges the entries of a
37
+ * build by plugin identity, so a fresh instance per entry would run its transform once per React page.
38
+ */
39
+ private readonly foreignBoundaryPlugin;
34
40
  private mdxLoaderPlugin;
35
41
  constructor(config: BundleServiceConfig);
36
42
  /**
@@ -24,6 +24,12 @@ export function getReactClientGraphAllowSpecifiers(routerAdapter) {
24
24
  export class BundleService {
25
25
  config;
26
26
  foreignJsxOverridePlugin;
27
+ /**
28
+ * @remarks
29
+ * One instance for every entry: its options do not depend on the entry, and core merges the entries of a
30
+ * build by plugin identity, so a fresh instance per entry would run its transform once per React page.
31
+ */
32
+ foreignBoundaryPlugin;
27
33
  mdxLoaderPlugin;
28
34
  constructor(config) {
29
35
  this.config = config;
@@ -38,6 +44,13 @@ export class BundleService {
38
44
  },
39
45
  }),
40
46
  });
47
+ this.foreignBoundaryPlugin = createForeignBoundaryPlugin({
48
+ projectRoot: config.appConfig?.absolutePaths?.projectDir ?? config.rootDir,
49
+ isForeignFile: (filePath) => {
50
+ const owner = findIntegrationForFile(config.appConfig?.integrations ?? [], filePath);
51
+ return owner !== undefined && owner.name !== config.hostIntegrationName;
52
+ },
53
+ });
41
54
  }
42
55
  /**
43
56
  * Creates bundle options for a page or component entry.
@@ -80,13 +93,7 @@ export class BundleService {
80
93
  return [
81
94
  ...(this.foreignJsxOverridePlugin ? [this.foreignJsxOverridePlugin] : []),
82
95
  graphBoundaryPlugin,
83
- createForeignBoundaryPlugin({
84
- projectRoot: this.config.appConfig?.absolutePaths?.projectDir ?? this.config.rootDir,
85
- isForeignFile: (filePath) => {
86
- const owner = findIntegrationForFile(this.config.appConfig?.integrations ?? [], filePath);
87
- return owner !== undefined && owner.name !== this.config.hostIntegrationName;
88
- },
89
- }),
96
+ this.foreignBoundaryPlugin,
90
97
  ...(mdxPlugin ? [mdxPlugin] : []),
91
98
  ];
92
99
  }
@@ -8,8 +8,8 @@ const SERVER_ONLY_ECO_PAGE_OPTION_KEYS = new Set([
8
8
  'dependencies',
9
9
  'requires',
10
10
  'metadata',
11
- 'staticProps',
12
- 'staticPaths',
11
+ 'props',
12
+ 'paths',
13
13
  ]);
14
14
  function isEcoPageOptionsCall(node) {
15
15
  return (node.type === 'CallExpression' &&
@@ -140,7 +140,7 @@ function assertNoStrippedBindingReferences(browserUnits, input) {
140
140
  if (!first)
141
141
  return;
142
142
  const specifier = input.strippedBindings.get(first.name);
143
- throw new Error(`[Ecopages Client Graph] '${first.name}' (imported from '${specifier}') is used at ${input.filename}:${toLineColumn(input.source, first.node.start)}, but that import is server-only and the browser build removes it. Use it only in server-only Page options such as middleware or staticProps, or in code the browser module does not reach.`);
143
+ throw new Error(`[Ecopages Client Graph] '${first.name}' (imported from '${specifier}') is used at ${input.filename}:${toLineColumn(input.source, first.node.start)}, but that import is server-only and the browser build removes it. Use it only in server-only Page options such as middleware or props, or in code the browser module does not reach. To use server code in the browser's render path, move it into a '.server' module and call it only from those options.`);
144
144
  }
145
145
  /**
146
146
  * Plans the removal of the top-level code the browser module does not need once server-only code is gone.
@@ -12,7 +12,6 @@ export type WalkImportsContext = {
12
12
  reachability: ReachabilityResult;
13
13
  edits: SourceEdit[];
14
14
  allowedMap: Map<string, Set<string> | '*'>;
15
- preserveUnreachableSideEffectImports: boolean;
16
15
  /** Receives the local name of each removed value binding, mapped to its import specifier. */
17
16
  strippedBindings: Map<string, string>;
18
17
  /** Receives each import declaration that gets an edit. */
@@ -11,10 +11,11 @@ function processSpecifier(specifier, allowedMap) {
11
11
  }
12
12
  return { allowed: true, rules: explicitRules ?? '*' };
13
13
  }
14
- function pruneForbiddenSpecifier(node, ctx, specifier, message, replacement) {
14
+ function pruneForbiddenSpecifier(node, ctx, specifier, message, replacement, bindings = []) {
15
15
  const reachableRules = ctx.reachability.reachableImports.get(specifier);
16
16
  if (reachableRules && !ctx.reachability.isFallbackRoots) {
17
- throw new Error(`[Ecopages Client Reachability] ${message} at ${ctx.filename}:${node.start}. This import is explicitly reachable from the React render function.`);
17
+ const used = bindings.length > 0 ? ` (${bindings.map((name) => `'${name}'`).join(', ')})` : '';
18
+ throw new Error(`[Ecopages Client Reachability] ${message} at ${ctx.filename}:${node.start}. This server-only import${used} is reachable from the React render function, which runs in the browser. Move the code that uses it into a '.server' module and call it only from server-only Page options such as props.`);
18
19
  }
19
20
  ctx.edits.push({ start: node.start, end: node.end, replacement });
20
21
  }
@@ -29,10 +30,10 @@ function recordStrippedBindings(node, specifier, ctx, isKept = () => false) {
29
30
  }
30
31
  function handleImportDeclaration(node, ctx) {
31
32
  const specifier = node.source.value;
32
- const reachableRules = ctx.reachability.reachableImports.get(specifier);
33
33
  const { allowed, rules } = processSpecifier(specifier, ctx.allowedMap);
34
34
  if (!allowed) {
35
- pruneForbiddenSpecifier(node, ctx, specifier, `Forbidden client import '${specifier}'`, '');
35
+ const bindings = (node.specifiers ?? []).map((specifierNode) => specifierNode.local.name);
36
+ pruneForbiddenSpecifier(node, ctx, specifier, `Forbidden client import '${specifier}'`, '', bindings);
36
37
  recordStrippedBindings(node, specifier, ctx);
37
38
  ctx.editedImports.add(node);
38
39
  return true;
@@ -46,12 +47,6 @@ function handleImportDeclaration(node, ctx) {
46
47
  }
47
48
  return true;
48
49
  }
49
- if (!ctx.preserveUnreachableSideEffectImports &&
50
- !reachableRules &&
51
- (!node.specifiers || node.specifiers.length === 0)) {
52
- ctx.edits.push({ start: node.start, end: node.end, replacement: '' });
53
- ctx.editedImports.add(node);
54
- }
55
50
  return true;
56
51
  }
57
52
  function handleExportNamedDeclaration(node, ctx) {
@@ -15,7 +15,7 @@ import { type RequestedExportRules } from './specifier-classification.js';
15
15
  * @param requestedExports - The exports this module's importers use; `undefined` keeps every export.
16
16
  * @param parsed - The parse of `source`, when the caller already has it.
17
17
  */
18
- export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: RequestedExportRules | undefined, preserveUnreachableSideEffectImports?: boolean, parsed?: ParseResult['program']): {
18
+ export declare function transformModuleImports(source: string, filename: string, globallyAllowed: Map<string, Set<string> | '*'>, requestedExports: RequestedExportRules | undefined, parsed?: ParseResult['program']): {
19
19
  transformed: string;
20
20
  modified: boolean;
21
21
  };
@@ -34,7 +34,7 @@ function collectLocalDeclaredModules(program) {
34
34
  * @param requestedExports - The exports this module's importers use; `undefined` keeps every export.
35
35
  * @param parsed - The parse of `source`, when the caller already has it.
36
36
  */
37
- export function transformModuleImports(source, filename, globallyAllowed, requestedExports, preserveUnreachableSideEffectImports = false, parsed) {
37
+ export function transformModuleImports(source, filename, globallyAllowed, requestedExports, parsed) {
38
38
  let program = parsed;
39
39
  if (!program) {
40
40
  try {
@@ -54,7 +54,6 @@ export function transformModuleImports(source, filename, globallyAllowed, reques
54
54
  filename,
55
55
  reachability,
56
56
  allowedMap,
57
- preserveUnreachableSideEffectImports,
58
57
  strippedBindings,
59
58
  editedImports,
60
59
  });
@@ -9,7 +9,6 @@ export type TransformClientGraphModuleOptions = {
9
9
  category: ClientGraphModuleKind;
10
10
  globallyDeclaredSources: Map<string, Set<string> | '*'>;
11
11
  requestedExports: RequestedExportRules | undefined;
12
- preserveUnreachableSideEffectImports?: boolean;
13
12
  };
14
13
  /**
15
14
  * Applies import transforms to one client-graph module whose read-file calls are already inlined.
@@ -1,7 +1,6 @@
1
1
  import { path } from '@ecopages/file-system/path';
2
2
  import { recordModuleTransformProfile } from '@ecopages/core/build';
3
3
  import { transformModuleImports } from './ast-transform.js';
4
- import { isPageOrLayoutEntry } from './module-classification.js';
5
4
  function toLoaderResult(filePath, contents) {
6
5
  const ext = path.extname(filePath).slice(1);
7
6
  return { contents, loader: ext };
@@ -12,7 +11,7 @@ function toLoaderResult(filePath, contents) {
12
11
  export function transformClientGraphModule(options) {
13
12
  const { module } = options;
14
13
  const analysisStartedAt = performance.now();
15
- const { transformed, modified } = transformModuleImports(module.source, options.filePath, options.globallyDeclaredSources, options.requestedExports, Boolean(options.preserveUnreachableSideEffectImports) && !isPageOrLayoutEntry(options.filePath), module.program);
14
+ const { transformed, modified } = transformModuleImports(module.source, options.filePath, options.globallyDeclaredSources, options.requestedExports, module.program);
16
15
  recordModuleTransformProfile({
17
16
  category: options.category,
18
17
  phase: 'analysis',
@@ -139,7 +139,7 @@ async function takeModule(build, state, sourcePath, options, transforms) {
139
139
  state.loadedEntries.set(realPath, module);
140
140
  return { module, plan };
141
141
  }
142
- async function loadClientGraphBoundaryModule(build, args, options, state, transforms, isEntrypoint = options.entrypointFile === path.resolve(options.absWorkingDir, args.path)) {
142
+ async function loadClientGraphBoundaryModule(build, args, options, state, transforms) {
143
143
  const sourcePath = path.resolve(options.absWorkingDir, args.path);
144
144
  if (options.entrypointFile &&
145
145
  options.groupedEntrypointFiles.has(sourcePath) &&
@@ -168,7 +168,6 @@ async function loadClientGraphBoundaryModule(build, args, options, state, transf
168
168
  category,
169
169
  globallyDeclaredSources,
170
170
  requestedExports: plan?.requestedExports(sourcePath),
171
- preserveUnreachableSideEffectImports: !isEntrypoint,
172
171
  });
173
172
  }
174
173
  function resolveEntryImports(entrypointFiles, entrypoint) {
@@ -250,6 +249,19 @@ function getForeignJsxReach(context, projectRoot, isForeignFile) {
250
249
  }
251
250
  return context.foreignJsxReach;
252
251
  }
252
+ /**
253
+ * The file itself when it is a browser entry of the build that no React entry file claims.
254
+ *
255
+ * @remarks
256
+ * The import scan records only files an entry imports, so a foreign file that is bundled as its own entry, such
257
+ * as a Radiant script, is absent from it. Without this it would count as a file the scan did not find and keep
258
+ * React's override.
259
+ */
260
+ function findForeignEntry(context, filePath) {
261
+ const entryFiles = new Set([...context.entrypointFiles].map(toRealPath));
262
+ const reactEntryFiles = new Set([...getReactEntrypointFiles(context)].map(toRealPath));
263
+ return entryFiles.has(filePath) && !reactEntryFiles.has(filePath) ? filePath : undefined;
264
+ }
253
265
  /**
254
266
  * Scope for React's foreign-JSX override: a file another JSX Integration owns gets React's JSX runtime only when
255
267
  * a React entry file reaches it.
@@ -269,13 +281,15 @@ export function createForeignJsxScope(options) {
269
281
  return true;
270
282
  const reach = getForeignJsxReach(context, options.projectRoot, isForeignFile);
271
283
  const filePath = toRealPath(sourcePath);
272
- const otherEntry = reach.others.get(filePath);
284
+ const otherEntry = reach.others.get(filePath) ?? findForeignEntry(context, filePath);
273
285
  if (otherEntry === undefined)
274
286
  return true;
275
287
  if (!reach.react.has(filePath))
276
288
  return false;
277
- throw new Error(`[ecopages] ${filePath} is a ${owner} file that both ${options.hostIntegrationName} browser entries and ` +
278
- `another browser entry (${otherEntry}) import. ${options.hostIntegrationName} compiles it with its ` +
289
+ const importedBy = otherEntry === filePath
290
+ ? `is itself a browser entry and ${options.hostIntegrationName} browser entries import it`
291
+ : `that both ${options.hostIntegrationName} browser entries and another browser entry (${otherEntry}) import`;
292
+ throw new Error(`[ecopages] ${filePath} is a ${owner} file ${importedBy}. ${options.hostIntegrationName} compiles it with its ` +
279
293
  `own JSX runtime and ${owner} with its runtime, but one module has one compiled form. Import it ` +
280
294
  `from one of them only.`);
281
295
  };
@@ -307,7 +321,7 @@ export function createClientGraphBoundaryPlugin(options) {
307
321
  loadedEntries: new Map(),
308
322
  };
309
323
  const transforms = () => (filePath) => isTransformedSource(filePath, normalizedOptions.projectRoot);
310
- build.onLoad(SOURCE_FILES, (loaded) => loadClientGraphBoundaryModule(build, stripVariant(loaded), normalizedOptions, state, transforms, entrypointFiles.has(path.resolve(normalizedOptions.absWorkingDir, stripVariant(loaded).path))));
324
+ build.onLoad(SOURCE_FILES, (loaded) => loadClientGraphBoundaryModule(build, stripVariant(loaded), normalizedOptions, state, transforms));
311
325
  return;
312
326
  }
313
327
  const context = getBuildContext(build.entrypoints, normalizedOptions);
@@ -367,7 +381,7 @@ export function createForeignBoundaryPlugin(options) {
367
381
  };
368
382
  });
369
383
  build.transform({ filter: /\.(?:[cm]?[jt]sx?|mdx?)$/, exclude: /^\0|\/node_modules\// }, (code, id) => {
370
- const filePath = toRealPath(id.replace(/[?#].*$/, ''));
384
+ const filePath = id.replace(/[?#].*$/, '');
371
385
  if (options.isForeignFile(filePath))
372
386
  return undefined;
373
387
  const context = build.entrypoints ? buildContexts.get(build.entrypoints) : undefined;
@@ -4,7 +4,6 @@
4
4
  import { fileSystem } from '@ecopages/file-system';
5
5
  import { parseModuleSource, resolveProjectModulePath } from '@ecopages/core/build';
6
6
  import { FOREIGN_BOUNDARY_PACKAGE } from '../bundling/bootstrap-package-paths.js';
7
- import { toRealPath } from './foreign-jsx-reach.js';
8
7
  import { collectLexicalDeclarations, walkScopedReferences } from './scope-walk.js';
9
8
  const HELPER_BINDING = '__ecoForeignBoundary';
10
9
  const NAMESPACE_HELPER_BINDING = '__ecoForeignBoundaryNamespace';
@@ -34,11 +33,12 @@ class ForeignExports {
34
33
  constructor(options) {
35
34
  this.options = options;
36
35
  }
36
+ /**
37
+ * @remarks
38
+ * `preserveBarrel` makes {@link resolveProjectModulePath} return the real path, so it is not resolved again.
39
+ */
37
40
  resolve(importer, specifier) {
38
- const resolved = resolveProjectModulePath(this.options.projectRoot, importer, specifier, {
39
- preserveBarrel: true,
40
- });
41
- return resolved ? toRealPath(resolved) : undefined;
41
+ return resolveProjectModulePath(this.options.projectRoot, importer, specifier, { preserveBarrel: true });
42
42
  }
43
43
  getReexports(filePath) {
44
44
  let nodes = this.reexports.get(filePath);
@@ -1,7 +1,8 @@
1
1
  import { path } from '@ecopages/file-system/path';
2
2
  import { fileSystem } from '@ecopages/file-system';
3
- import { resolveProjectModulePath } from '@ecopages/core/build';
4
- const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*)(['"])([^'"\n]+)\1/g;
3
+ import { parseModuleSource, resolveProjectModulePath } from '@ecopages/core/build';
4
+ import { compileSync } from '@mdx-js/mdx';
5
+ const MDX_SOURCE = /\.mdx?$/;
5
6
  const SCANNED_SOURCE = /\.(?:[cm]?[jt]sx?|mdx?)$/;
6
7
  /** `filePath` with symbolic links resolved, so paths from the build and from the scan compare equal. */
7
8
  export function toRealPath(filePath) {
@@ -12,15 +13,40 @@ export function toRealPath(filePath) {
12
13
  return path.resolve(filePath);
13
14
  }
14
15
  }
16
+ /**
17
+ * Reads the module specifiers of a file from its parsed module: static imports, `export ... from` and dynamic
18
+ * `import()` with a literal specifier.
19
+ *
20
+ * @remarks
21
+ * The parser does not read MDX, so an MDX file is compiled first and its output parsed. A file that does not read,
22
+ * compile or parse has no specifiers.
23
+ */
15
24
  function readImportSpecifiers(filePath) {
16
- let source;
17
25
  try {
18
- source = fileSystem.readFileSync(filePath);
26
+ let source = fileSystem.readFileSync(filePath);
27
+ let parsePath = filePath;
28
+ if (MDX_SOURCE.test(filePath)) {
29
+ source = String(compileSync(source, { format: filePath.endsWith('.md') ? 'md' : 'mdx' }));
30
+ parsePath = `${filePath}.jsx`;
31
+ }
32
+ const { module } = parseModuleSource(parsePath, source);
33
+ return [
34
+ ...module.staticImports.map((entry) => entry.moduleRequest.value),
35
+ ...module.staticExports.flatMap((entry) => entry.entries.map((exported) => exported.moduleRequest?.value)),
36
+ ...module.dynamicImports.map((entry) => literalSpecifier(source, entry.moduleRequest)),
37
+ ].filter((specifier) => typeof specifier === 'string');
19
38
  }
20
39
  catch {
21
40
  return [];
22
41
  }
23
- return [...source.matchAll(IMPORT_SPECIFIER)].map((match) => match[2]);
42
+ }
43
+ /** The specifier of a dynamic `import()` when its argument is a plain string literal, otherwise `undefined`. */
44
+ function literalSpecifier(source, span) {
45
+ const text = source.slice(span.start, span.end);
46
+ const quote = text[0];
47
+ if ((quote !== "'" && quote !== '"') || text.at(-1) !== quote)
48
+ return undefined;
49
+ return text.slice(1, -1);
24
50
  }
25
51
  /**
26
52
  * Walks the static imports of the app's own source files from `roots`, never into a file in `stopAt`, and
@@ -1,3 +1,2 @@
1
1
  export type ClientGraphModuleKind = 'app' | 'workspace' | 'package' | 'vendored' | 'virtual';
2
2
  export declare function classifyClientGraphModule(filePath: string, projectRoot?: string): ClientGraphModuleKind;
3
- export declare function isPageOrLayoutEntry(filePath: string): boolean;
@@ -30,7 +30,3 @@ export function classifyClientGraphModule(filePath, projectRoot) {
30
30
  }
31
31
  return 'workspace';
32
32
  }
33
- export function isPageOrLayoutEntry(filePath) {
34
- const segments = pathSegments(filePath);
35
- return segments.includes('pages') || segments.includes('layouts');
36
- }
@@ -13,7 +13,6 @@ import type { ExplicitlyRequestedExports } from './reachability-export-names.js'
13
13
  export type ReachabilityResult = {
14
14
  reachableImports: Map<string, Set<string> | '*'>;
15
15
  reachableDeclarations: Set<unknown>;
16
- unreachableSideEffectImports: unknown[];
17
16
  isFallbackRoots: boolean;
18
17
  analyzed: boolean;
19
18
  };
@@ -13,7 +13,6 @@ function emptyReachabilityResult(isFallbackRoots) {
13
13
  return {
14
14
  reachableImports: new Map(),
15
15
  reachableDeclarations: new Set(),
16
- unreachableSideEffectImports: [],
17
16
  isFallbackRoots,
18
17
  analyzed: false,
19
18
  };
@@ -40,13 +39,9 @@ export function analyzeReachability(source, filename, program, explicitlyRequest
40
39
  const potentialClientRoots = index.clientRoots;
41
40
  const isFallbackRoots = resolveFallbackClientRoots(resolvedProgram, potentialClientRoots, explicitlyRequestedExports);
42
41
  const { reachableImports, reachableDeclarations } = runReachabilityTraversal(potentialClientRoots, index.topLevelImports, index.topLevelDeclarations, explicitlyRequestedExports);
43
- const unreachableSideEffectImports = index.topLevelImports
44
- .filter((imp) => imp.isSideEffect && !reachableImports.has(imp.specifier))
45
- .map((imp) => imp.node);
46
42
  return {
47
43
  reachableImports,
48
44
  reachableDeclarations,
49
- unreachableSideEffectImports,
50
45
  isFallbackRoots,
51
46
  analyzed: true,
52
47
  };
@@ -44,7 +44,7 @@ export type RequestedExportsPlan = {
44
44
  * A module's pruning depends on the exports its importers request, so computing them while modules load
45
45
  * made the result depend on which importer Rolldown loaded first. The plan starts from the build's entries
46
46
  * and follows only the imports a module's browser code reaches, after server-only Page options are set
47
- * aside, as the boundary's own analysis finds them: a module reached only through a stripped `staticProps`
47
+ * aside, as the boundary's own analysis finds them: a module reached only through a stripped `props`
48
48
  * is never loaded, so it requests nothing. A module the boundary does not transform, such as a
49
49
  * bootstrap entry, passes every import on and requests nothing. Requested exports flow from importers to
50
50
  * imports through a worklist that analyses a module again whenever its requests grow, so a cycle settles on
@@ -37,7 +37,7 @@ function statementSpecifiers(program) {
37
37
  * A module's pruning depends on the exports its importers request, so computing them while modules load
38
38
  * made the result depend on which importer Rolldown loaded first. The plan starts from the build's entries
39
39
  * and follows only the imports a module's browser code reaches, after server-only Page options are set
40
- * aside, as the boundary's own analysis finds them: a module reached only through a stripped `staticProps`
40
+ * aside, as the boundary's own analysis finds them: a module reached only through a stripped `props`
41
41
  * is never loaded, so it requests nothing. A module the boundary does not transform, such as a
42
42
  * bootstrap entry, passes every import on and requests nothing. Requested exports flow from importers to
43
43
  * imports through a worklist that analyses a module again whenever its requests grow, so a cycle settles on
@@ -3,7 +3,7 @@
3
3
  */
4
4
  import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from '@ecopages/core/build';
5
5
  import { toPackageRootSpecifier } from '@ecopages/core/build';
6
- import { isContentServerVirtualModule } from '@ecopages/core/build';
6
+ import { isContentServerVirtualModule, isNodeBuiltinSpecifier } from '@ecopages/core/build';
7
7
  import { isServerOnlyModuleSpecifier } from '@ecopages/core/build/contracts';
8
8
  import { path } from '@ecopages/file-system/path';
9
9
  export function isBareSpecifier(specifier) {
@@ -35,7 +35,7 @@ export function isProjectAliasSpecifier(specifier, projectRoot) {
35
35
  * @returns True when the import must never become client-reachable.
36
36
  */
37
37
  export function isServerOnlySpecifier(specifier) {
38
- if (specifier.startsWith('node:'))
38
+ if (isNodeBuiltinSpecifier(specifier))
39
39
  return true;
40
40
  if (isContentServerVirtualModule(specifier))
41
41
  return true;
@@ -39,8 +39,8 @@ export declare class ReactHmrStrategy extends HmrStrategy {
39
39
  private isReactEntrypoint;
40
40
  /**
41
41
  * @remarks
42
- * React integration owns plain `.tsx` route templates. Compound extensions in
43
- * pages/layouts are integration-specific route templates and should not be
42
+ * React integration owns plain `.tsx` route templates: the Route Registry's Pages and the modules Pages
43
+ * reference as Layouts. Compound extensions in them are integration-specific route templates and should not be
44
44
  * claimed by React HMR strategy.
45
45
  */
46
46
  private isRouteTemplate;
@@ -91,12 +91,12 @@ export class ReactHmrStrategy extends HmrStrategy {
91
91
  }
92
92
  /**
93
93
  * @remarks
94
- * React integration owns plain `.tsx` route templates. Compound extensions in
95
- * pages/layouts are integration-specific route templates and should not be
94
+ * React integration owns plain `.tsx` route templates: the Route Registry's Pages and the modules Pages
95
+ * reference as Layouts. Compound extensions in them are integration-specific route templates and should not be
96
96
  * claimed by React HMR strategy.
97
97
  */
98
98
  isRouteTemplate(filePath) {
99
- return (isPathInside(filePath, this.context.getPagesDir()) || isPathInside(filePath, this.context.getLayoutsDir()));
99
+ return this.context.isPageFile(filePath) || this.context.isLayoutFile(filePath);
100
100
  }
101
101
  resolveTemplateExtension(filePath) {
102
102
  return this.allTemplateExtensions.find((extension) => filePath.endsWith(extension));
@@ -172,10 +172,10 @@ export class ReactHmrStrategy extends HmrStrategy {
172
172
  return buildReactDevTransformPlugins(this.getDevTransformPluginOptions(), declaredModules, sourcePath.endsWith('.mdx'));
173
173
  }
174
174
  isLayoutFile(filePath) {
175
- return isPathInside(filePath, this.context.getLayoutsDir());
175
+ return this.context.isLayoutFile(filePath);
176
176
  }
177
177
  isPageEntrypoint(filePath) {
178
- return isPathInside(filePath, this.context.getPagesDir()) && this.isReactEntrypoint(filePath);
178
+ return this.context.isPageFile(filePath) && this.isReactEntrypoint(filePath);
179
179
  }
180
180
  resolveEntrypointOutputUrl(entrypointPath) {
181
181
  return this.context.getWatchedFiles().get(path.resolve(entrypointPath));
@@ -43,7 +43,7 @@ async function applyRouterHmrUpdate(options, newUrl, currentPage, nextPage) {
43
43
  * document, and the live boundary of a hydrated custom element no longer holds its declarative shadow root. The
44
44
  * parsed document keeps the `<template shadowrootmode>` of each, as a client navigation's does. A response that is
45
45
  * not a page, such as a server render error, throws, so the update is not applied and the next edit retries it.
46
- * The same document is the source of the Page's props, and of its module URL when the page data carries one, since an edit can change what `staticProps`
46
+ * The same document is the source of the Page's props, and of its module URL when the page data carries one, since an edit can change what `props`
47
47
  * returns and the live `__ECO_PAGE_DATA__` still holds the old values.
48
48
  */
49
49
  async function fetchCurrentDocument() {
@@ -12,8 +12,6 @@ import { type EcoComponentConfig, type EcoPageFile } from '@ecopages/core';
12
12
  * Configuration for the PageModuleService.
13
13
  */
14
14
  export interface PageModuleServiceConfig {
15
- layoutsDir?: string;
16
- componentsDir?: string;
17
15
  mdxExtensions: string[];
18
16
  integrationName: string;
19
17
  hasRouterAdapter: boolean;
@@ -30,6 +28,10 @@ export declare class PageModuleService {
30
28
  isMdxFile(filePath: string): boolean;
31
29
  /**
32
30
  * Ensures that an EcoComponentConfig has canonical identity attached.
31
+ *
32
+ * @remarks
33
+ * A config the build stamped keeps its identity. One without it was not declared by a literal `eco.*` call, so
34
+ * it is bound to the page that reached it and its relative paths resolve against that page.
33
35
  */
34
36
  ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
35
37
  hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
@@ -7,10 +7,8 @@
7
7
  *
8
8
  * @module
9
9
  */
10
- import { path } from '@ecopages/file-system/path';
11
10
  import { bindComponentIdentity, getComponentIdentity, getComponentOwner, } from '@ecopages/core';
12
11
  import { contentHash } from '@ecopages/core/build';
13
- import { fileSystem } from '@ecopages/file-system';
14
12
  import { someInConfigTree } from '../client-graph/component-config-traversal.js';
15
13
  import { collectPageDeclaredModulesFromModule } from '../client-graph/declared-modules.js';
16
14
  /**
@@ -29,34 +27,21 @@ export class PageModuleService {
29
27
  }
30
28
  /**
31
29
  * Ensures that an EcoComponentConfig has canonical identity attached.
30
+ *
31
+ * @remarks
32
+ * A config the build stamped keeps its identity. One without it was not declared by a literal `eco.*` call, so
33
+ * it is bound to the page that reached it and its relative paths resolve against that page.
32
34
  */
33
35
  ensureConfigFileMetadata(config, pagePath) {
34
36
  const identity = getComponentIdentity(config);
35
37
  if (identity?.file) {
36
38
  return config;
37
39
  }
38
- const buildIdentity = (file) => ({
39
- id: identity?.id ?? BigInt(`0x${contentHash(file, 16)}`).toString(36),
40
+ return bindComponentIdentity({
41
+ id: identity?.id ?? BigInt(`0x${contentHash(pagePath, 16)}`).toString(36),
40
42
  integration: getComponentOwner(config, this.config.integrationName),
41
- file,
42
- });
43
- const resolveDependencyValue = (value) => typeof value === 'string' ? value : value.src;
44
- const dependencyPaths = [
45
- ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
46
- ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue),
47
- ]
48
- .filter((value) => Boolean(value))
49
- .filter((value) => value.startsWith('./') || value.startsWith('../'));
50
- const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter((value) => typeof value === 'string' && value.length > 0);
51
- for (const dependencyPath of dependencyPaths) {
52
- for (const candidateDir of candidateDirs) {
53
- const resolvedDependency = path.resolve(candidateDir, dependencyPath);
54
- if (fileSystem.exists(resolvedDependency)) {
55
- return bindComponentIdentity(buildIdentity(path.join(candidateDir, path.basename(pagePath))), config);
56
- }
57
- }
58
- }
59
- return bindComponentIdentity(buildIdentity(pagePath), config);
43
+ file: pagePath,
44
+ }, config);
60
45
  }
61
46
  hasModulesInConfig(config) {
62
47
  return someInConfigTree(config, (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false);
@@ -12,7 +12,6 @@ import { AsyncLocalStorage } from 'node:async_hooks';
12
12
  import { buildIslandHostAttributes, getComponentIdentity } from '@ecopages/core';
13
13
  import { createIntegrationRenderer, selectHydrationIslandEntries, } from '@ecopages/core/integration';
14
14
  import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from '@ecopages/core/client';
15
- import { resolveQueuedTokens } from '@ecopages/core/integration';
16
15
  import { ensurePageConfigLayouts, moveMdxMetadataOntoPage } from '@ecopages/core/integration';
17
16
  import { hasSingleRootElement } from './html-boundary.js';
18
17
  import { toRootRelativePath } from '@ecopages/core/build';
@@ -60,7 +59,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
60
59
  this.hookTargets.buildIslandClientAssets = (plan) => this.buildPageClientBrowserAssetsHook(plan);
61
60
  this.hookTargets.collectAppBrowserClientBuildEntries = (plan) => this.collectAppBrowserClientBuildEntriesHook(plan);
62
61
  this.hookTargets.renderComponent = (input) => this.renderComponentHook(input);
63
- this.hookTargets.renderQueuedChildren = (children, runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderQueuedChildrenHook(children, runtimeContext, queuedResolutionsByToken, resolveToken);
62
+ this.hookTargets.renderQueuedChildren = (children, runtimeContext, resolveTokens) => this.renderQueuedChildrenHook(children, runtimeContext, resolveTokens);
64
63
  this.hookTargets.normalizePageModule = (file, module) => this.normalizeImportedPageFileHook(file, module);
65
64
  this.hookTargets.collectPageBrowserGraphContribution = (context) => this.collectPageBrowserGraphContributionHook(context);
66
65
  this.hookTargets.composeChildren = ({ page, layouts, foreignChildRoots }) => this.resolveComposeChildren({ page, shellLayouts: layouts, foreignChildRoots });
@@ -167,24 +166,23 @@ export class ReactRenderer extends ReactIntegrationRenderer {
167
166
  * Resolves the Foreign Subtree tokens in `html`, wrapping them in the hydration boundary only when `hydrates`.
168
167
  */
169
168
  resolveReactQueuedForeignSubtreeHtml(html, runtimeContext, hydrates) {
170
- return this.resolveQueuedForeignSubtrees(hydrates ? wrapForeignSubtreeTokens(html, runtimeContext) : html, runtimeContext, async (children, currentRuntimeContext, queuedResolutionsByToken, resolveToken) => ({
169
+ return this.resolveQueuedForeignSubtrees(hydrates ? wrapForeignSubtreeTokens(html, runtimeContext) : html, runtimeContext, async (children, currentRuntimeContext, resolveTokens) => ({
171
170
  html: await this.renderQueuedChildrenToHtml({
172
171
  children,
173
172
  runtimeContext: currentRuntimeContext,
174
- queuedResolutionsByToken,
175
- resolveToken,
173
+ resolveTokens,
176
174
  }),
177
175
  }));
178
176
  }
179
177
  async renderQueuedChildrenToHtml(options) {
180
- const { children, runtimeContext, queuedResolutionsByToken, resolveToken } = options;
178
+ const { children, runtimeContext, resolveTokens } = options;
181
179
  if (children === undefined) {
182
180
  return undefined;
183
181
  }
184
182
  const runtime = this.getReactRuntimeModules();
185
- let html = this.normalizeUnresolvedMarkerArtifactHtml(await this.renderReactTree(runtime.react.createElement(runtime.react.Fragment, null, toReactNode(children, this.name)), 'queued children'));
183
+ let html = await this.renderReactTree(runtime.react.createElement(runtime.react.Fragment, null, toReactNode(children, this.name)), 'queued children');
186
184
  html = restoreRuntimeChildHtml(html, runtimeContext);
187
- return await resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken);
185
+ return await resolveTokens(html);
188
186
  }
189
187
  buildPagePayload(options) {
190
188
  const safeLocals = this.pagePayloadService.getSerializableLocals(options.locals, getComponentRequires(options.Page));
@@ -249,14 +247,14 @@ export class ReactRenderer extends ReactIntegrationRenderer {
249
247
  componentInstanceId: input.integrationContext?.componentInstanceId,
250
248
  };
251
249
  const hasResolvedChildHtml = input.children !== undefined;
252
- let html = this.normalizeUnresolvedMarkerArtifactHtml(await renderComponentHtml({
250
+ let html = await renderComponentHtml({
253
251
  input,
254
252
  context,
255
253
  runtimeContext,
256
254
  runtime: this.getReactRuntimeModules(),
257
255
  timeoutMs: this.getRuntimeState().renderTimeoutMs,
258
256
  label: getComponentIdentity(input.component)?.file ?? 'component',
259
- }));
257
+ });
260
258
  const componentFile = getComponentIdentity(componentConfig)?.file;
261
259
  const isIslandRoot = Boolean(componentFile && context.componentInstanceId && !hasResolvedChildHtml) &&
262
260
  hasSingleRootElement(replaceForeignSubtreeTokens(html, runtimeContext, '<x></x>'));
@@ -281,15 +279,14 @@ export class ReactRenderer extends ReactIntegrationRenderer {
281
279
  rootAttributes,
282
280
  };
283
281
  }
284
- async renderQueuedChildrenHook(children, runtimeContext, queuedResolutionsByToken, resolveToken) {
282
+ async renderQueuedChildrenHook(children, runtimeContext, resolveTokens) {
285
283
  if (children === undefined) {
286
284
  return {};
287
285
  }
288
286
  const html = await this.renderQueuedChildrenToHtml({
289
287
  children,
290
288
  runtimeContext: runtimeContext,
291
- queuedResolutionsByToken,
292
- resolveToken,
289
+ resolveTokens,
293
290
  });
294
291
  return html === undefined ? {} : { html };
295
292
  }
@@ -358,7 +355,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
358
355
  },
359
356
  };
360
357
  const runtimeContext = this.getQueuedForeignSubtreeContext(runtimeInput);
361
- const html = this.normalizeUnresolvedMarkerArtifactHtml(await this.renderReactTree(tree, getComponentIdentity(page.component)?.file ?? 'page'));
358
+ const html = await this.renderReactTree(tree, getComponentIdentity(page.component)?.file ?? 'page');
362
359
  const layoutWithoutChildren = renderTracker.findLayoutWithoutChildren(page.component);
363
360
  if (layoutWithoutChildren)
364
361
  this.onLayoutChildrenNotRendered(layoutWithoutChildren);
@@ -464,8 +461,6 @@ function createReactRendererHookFactory(reactConfig, runtimeStateRef, hookTarget
464
461
  getMdxLoaderPlugin: reactConfig?.getMdxLoaderPlugin,
465
462
  });
466
463
  const pageModuleService = new PageModuleService({
467
- layoutsDir: appConfig.absolutePaths.layoutsDir,
468
- componentsDir: appConfig.absolutePaths.componentsDir,
469
464
  mdxExtensions,
470
465
  integrationName: REACT_PLUGIN_NAME,
471
466
  hasRouterAdapter: Boolean(routerAdapter),
@@ -500,7 +495,7 @@ function createReactRendererHookFactory(reactConfig, runtimeStateRef, hookTarget
500
495
  buildIslandClientAssets: (plan) => requireReactRendererHookTarget(hookTargets, 'buildIslandClientAssets')(plan),
501
496
  collectAppBrowserClientBuildEntries: (plan) => requireReactRendererHookTarget(hookTargets, 'collectAppBrowserClientBuildEntries')(plan),
502
497
  renderComponent: (input) => requireReactRendererHookTarget(hookTargets, 'renderComponent')(input),
503
- renderQueuedChildren: (children, runtimeContext, queuedResolutionsByToken, resolveToken) => requireReactRendererHookTarget(hookTargets, 'renderQueuedChildren')(children, runtimeContext, queuedResolutionsByToken, resolveToken),
498
+ renderQueuedChildren: (children, runtimeContext, resolveTokens) => requireReactRendererHookTarget(hookTargets, 'renderQueuedChildren')(children, runtimeContext, resolveTokens),
504
499
  normalizePageModule: (file, module) => requireReactRendererHookTarget(hookTargets, 'normalizePageModule')(file, module),
505
500
  collectPageBrowserGraphContribution: (context) => requireReactRendererHookTarget(hookTargets, 'collectPageBrowserGraphContribution')(context),
506
501
  composeChildren: (input) => requireReactRendererHookTarget(hookTargets, 'composeChildren')(input),