@ecopages/react 0.6.1 → 0.7.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 (95) hide show
  1. package/README.md +50 -87
  2. package/package.json +32 -14
  3. package/src/bundling/bootstrap-package-paths.d.ts +13 -1
  4. package/src/bundling/bootstrap-package-paths.js +25 -3
  5. package/src/bundling/bundle.d.ts +8 -36
  6. package/src/bundling/bundle.js +42 -73
  7. package/src/client-graph/ast-transform-eco-page.d.ts +10 -6
  8. package/src/client-graph/ast-transform-eco-page.js +56 -35
  9. package/src/client-graph/ast-transform-import-edits.d.ts +10 -2
  10. package/src/client-graph/ast-transform-import-edits.js +36 -6
  11. package/src/client-graph/ast-transform-stripped-imports.d.ts +37 -0
  12. package/src/client-graph/ast-transform-stripped-imports.js +191 -0
  13. package/src/client-graph/ast-transform-walk-imports.d.ts +4 -0
  14. package/src/client-graph/ast-transform-walk-imports.js +15 -1
  15. package/src/client-graph/ast-transform.d.ts +12 -3
  16. package/src/client-graph/ast-transform.js +41 -56
  17. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +3 -0
  18. package/src/client-graph/boundary-plugin-read-file-inline.js +14 -10
  19. package/src/client-graph/boundary-plugin-transform.d.ts +5 -4
  20. package/src/client-graph/boundary-plugin-transform.js +6 -13
  21. package/src/client-graph/boundary-plugin.d.ts +47 -1
  22. package/src/client-graph/boundary-plugin.js +267 -53
  23. package/src/client-graph/foreign-boundary-rewrite.d.ts +31 -0
  24. package/src/client-graph/foreign-boundary-rewrite.js +360 -0
  25. package/src/client-graph/foreign-jsx-reach.d.ts +25 -0
  26. package/src/client-graph/foreign-jsx-reach.js +68 -0
  27. package/src/client-graph/module-classification.js +3 -10
  28. package/src/client-graph/reachability-traverse.js +35 -105
  29. package/src/client-graph/requested-exports-plan.d.ts +62 -0
  30. package/src/client-graph/requested-exports-plan.js +125 -0
  31. package/src/client-graph/scope-walk.d.ts +37 -0
  32. package/src/client-graph/scope-walk.js +407 -0
  33. package/src/client-graph/specifier-classification.d.ts +2 -1
  34. package/src/client-graph/specifier-classification.js +9 -7
  35. package/src/contracts/router-adapter.d.ts +9 -24
  36. package/src/dev-transform/react-dev-transform-contributor.d.ts +4 -4
  37. package/src/dev-transform/react-dev-transform-contributor.js +6 -7
  38. package/src/hmr/hmr-strategy-process.d.ts +7 -5
  39. package/src/hmr/hmr-strategy-process.js +21 -16
  40. package/src/hmr/hmr-strategy.d.ts +11 -10
  41. package/src/hmr/hmr-strategy.js +32 -53
  42. package/src/hmr/page-metadata-cache.js +1 -1
  43. package/src/hydration/browser/foreign-boundary.d.ts +29 -0
  44. package/src/hydration/browser/foreign-boundary.js +128 -0
  45. package/src/hydration/browser/island-hydration.d.ts +3 -4
  46. package/src/hydration/browser/island-hydration.js +3 -4
  47. package/src/hydration/browser/page-hydration-hmr.d.ts +8 -7
  48. package/src/hydration/browser/page-hydration-hmr.js +53 -10
  49. package/src/hydration/browser/page-hydration.d.ts +6 -5
  50. package/src/hydration/browser/page-hydration.js +8 -6
  51. package/src/hydration/foreign-subtree.d.ts +27 -0
  52. package/src/hydration/foreign-subtree.js +69 -0
  53. package/src/hydration/hydration-asset.d.ts +37 -29
  54. package/src/hydration/hydration-asset.js +74 -138
  55. package/src/hydration/hydration-island-entry-source.d.ts +17 -0
  56. package/src/hydration/hydration-island-entry-source.js +32 -0
  57. package/src/hydration/hydration-page-entry-source.d.ts +20 -2
  58. package/src/hydration/hydration-page-entry-source.js +17 -12
  59. package/src/hydration/page-data-reader.d.ts +4 -7
  60. package/src/hydration/page-data-reader.js +5 -10
  61. package/src/mdx/mdx-config-dependency.d.ts +10 -15
  62. package/src/mdx/mdx-config-dependency.js +9 -22
  63. package/src/mdx/mdx-loader-plugin.d.ts +2 -0
  64. package/src/mdx/mdx-loader-plugin.js +1 -0
  65. package/src/page/page-module.js +1 -1
  66. package/src/plugin/react.plugin.d.ts +0 -7
  67. package/src/plugin/react.plugin.js +4 -33
  68. package/src/plugin/react.types.d.ts +0 -29
  69. package/src/render/component-ssr.d.ts +18 -0
  70. package/src/render/component-ssr.js +37 -0
  71. package/src/render/layout-compose.d.ts +4 -2
  72. package/src/render/layout-compose.js +13 -6
  73. package/src/render/layout-render-tracker.d.ts +20 -0
  74. package/src/render/layout-render-tracker.js +33 -0
  75. package/src/render/react-renderer.d.ts +28 -10
  76. package/src/render/react-renderer.js +103 -38
  77. package/src/render/react-runtime.js +2 -2
  78. package/src/bundling/runtime-alias-map.d.ts +0 -12
  79. package/src/bundling/runtime-alias-map.js +0 -110
  80. package/src/bundling/runtime-bundle.d.ts +0 -70
  81. package/src/bundling/runtime-bundle.js +0 -233
  82. package/src/bundling/runtime-interop-plugin.d.ts +0 -5
  83. package/src/bundling/runtime-interop-plugin.js +0 -32
  84. package/src/bundling/runtime-mode.d.ts +0 -1
  85. package/src/bundling/runtime-mode.js +0 -10
  86. package/src/bundling/runtime-modules.d.ts +0 -21
  87. package/src/bundling/runtime-modules.js +0 -28
  88. package/src/hydration/bootstrap-imports.d.ts +0 -25
  89. package/src/hydration/bootstrap-imports.js +0 -33
  90. package/src/hydration/compiled-page-hydration-options.d.ts +0 -19
  91. package/src/hydration/compiled-page-hydration-options.js +0 -1
  92. package/src/hydration/hydration-script-compiler.d.ts +0 -47
  93. package/src/hydration/hydration-script-compiler.js +0 -213
  94. package/src/runtime/use-sync-external-store-with-selector.d.ts +0 -3
  95. package/src/runtime/use-sync-external-store-with-selector.js +0 -54
@@ -5,7 +5,7 @@ import { loadTsconfigPathPrefixes, matchesTsconfigPathPrefix } from '@ecopages/c
5
5
  import { toPackageRootSpecifier } from '@ecopages/core/build';
6
6
  import { isContentServerVirtualModule } from '@ecopages/core/build';
7
7
  import { isServerOnlyModuleSpecifier } from '@ecopages/core/build/contracts';
8
- import { dirname, resolve } from 'node:path';
8
+ import { path } from '@ecopages/file-system/path';
9
9
  export function isBareSpecifier(specifier) {
10
10
  if (specifier.startsWith('.'))
11
11
  return false;
@@ -139,8 +139,7 @@ export function mergeDeclaredModulesMap(a, b) {
139
139
  return result;
140
140
  }
141
141
  export function normalizeRequestedExportsKey(pathname) {
142
- let normalized = pathname.replace(/\\/g, '/');
143
- normalized = normalized.replace(/\.(tsx?|jsx?)$/i, '');
142
+ let normalized = pathname.replace(/\.(tsx?|jsx?)$/i, '');
144
143
  if (normalized.endsWith('/index')) {
145
144
  normalized = normalized.slice(0, -'/index'.length);
146
145
  }
@@ -160,7 +159,7 @@ export function resolveRequestedExportsKey(importer, specifier) {
160
159
  if (isBareSpecifier(specifier) || isProjectAliasSpecifier(specifier)) {
161
160
  return undefined;
162
161
  }
163
- const resolved = specifier.startsWith('/') ? specifier : resolve(dirname(importer), specifier);
162
+ const resolved = specifier.startsWith('/') ? specifier : path.resolve(path.dirname(importer), specifier);
164
163
  return normalizeRequestedExportsKey(resolved);
165
164
  }
166
165
  /**
@@ -172,20 +171,23 @@ export function resolveRequestedExportsKey(importer, specifier) {
172
171
  * @param registry - Cross-module requested-export registry.
173
172
  * @param moduleKey - Normalized local module key.
174
173
  * @param rules - Newly observed reachable export rules for the module.
174
+ * @returns Whether the registry changed.
175
175
  */
176
176
  export function mergeRequestedExportRules(registry, moduleKey, rules) {
177
177
  const existing = registry.get(moduleKey);
178
178
  if (existing === '*')
179
- return;
179
+ return false;
180
180
  if (rules === '*') {
181
181
  registry.set(moduleKey, '*');
182
- return;
182
+ return true;
183
183
  }
184
184
  if (!existing) {
185
185
  registry.set(moduleKey, new Set(rules));
186
- return;
186
+ return true;
187
187
  }
188
+ const size = existing.size;
188
189
  for (const rule of rules) {
189
190
  existing.add(rule);
190
191
  }
192
+ return existing.size !== size;
191
193
  }
@@ -11,11 +11,7 @@
11
11
  * ```ts
12
12
  * const myRouter: ReactRouterAdapter = {
13
13
  * name: 'my-router',
14
- * bundle: {
15
- * importPath: '@my/router/browser',
16
- * outputName: 'my-router',
17
- * externals: ['react', 'react-dom'],
18
- * },
14
+ * importPath: '@my/router/browser',
19
15
  * components: {
20
16
  * router: 'MyRouter',
21
17
  * pageContent: 'PageOutlet',
@@ -30,26 +26,15 @@ export interface ReactRouterAdapter {
30
26
  */
31
27
  name: string;
32
28
  /**
33
- * Runtime bundle configuration.
29
+ * Package specifier of the router's browser entry, which page bootstraps import.
30
+ *
31
+ * @remarks
32
+ * It resolves like any other package: production bundles it into the app-wide build and development serves it
33
+ * from the vendor graph, so it shares React with the Pages.
34
+ *
35
+ * @example '@ecopages/react-router/browser'
34
36
  */
35
- bundle: {
36
- /**
37
- * Node module import path for the browser-compatible entry.
38
- * @example '@ecopages/react-router/browser'
39
- */
40
- importPath: string;
41
- /**
42
- * Output filename (without extension).
43
- * @example 'my-router'
44
- */
45
- outputName: string;
46
- /**
47
- * Packages to externalize when bundling.
48
- * These should stay as bare runtime dependencies for the router bundle.
49
- * @example ['react', 'react-dom']
50
- */
51
- externals: string[];
52
- };
37
+ importPath: string;
53
38
  /**
54
39
  * Component names to import from the router package.
55
40
  */
@@ -1,5 +1,5 @@
1
1
  import type { EcoBuildPlugin } from '@ecopages/core/integration';
2
- import type { DevTransformBundleContributor } from '@ecopages/core/integration';
2
+ import type { DevTransformBundleContributor, DevTransformVendorEntries } from '@ecopages/core/integration';
3
3
  import type { ReactHmrStrategy } from '../hmr/hmr-strategy.js';
4
4
  export type ReactDevTransformContributorOptions = {
5
5
  strategy: ReactHmrStrategy;
@@ -10,8 +10,8 @@ export type ReactDevTransformContributorOptions = {
10
10
  export declare class ReactDevTransformContributor implements DevTransformBundleContributor {
11
11
  private readonly strategy;
12
12
  constructor(options: ReactDevTransformContributorOptions);
13
- ownsModule(sourcePath: string): boolean;
14
- getModulePlugins(sourcePath: string): Promise<readonly EcoBuildPlugin[]>;
15
- getRuntimeSpecifierMap(): ReadonlyMap<string, string>;
13
+ ownsModule(sourcePath: string, variant?: string): boolean;
14
+ getModulePlugins(sourcePath: string, variant?: string): Promise<readonly EcoBuildPlugin[]>;
15
+ getVendorEntries(): DevTransformVendorEntries;
16
16
  getVendorBundlePlugins(): Promise<readonly EcoBuildPlugin[]>;
17
17
  }
@@ -1,4 +1,3 @@
1
- import { getBrowserRuntimeSpecifierMap } from '@ecopages/core/build';
2
1
  /**
3
2
  * Supplies React module plugins for the core dev transform bundler.
4
3
  */
@@ -7,14 +6,14 @@ export class ReactDevTransformContributor {
7
6
  constructor(options) {
8
7
  this.strategy = options.strategy;
9
8
  }
10
- ownsModule(sourcePath) {
11
- return this.strategy.ownsDevTransformEntrypoint(sourcePath);
9
+ ownsModule(sourcePath, variant) {
10
+ return this.strategy.ownsDevTransformEntrypoint(sourcePath, variant);
12
11
  }
13
- async getModulePlugins(sourcePath) {
14
- return this.strategy.createDevTransformPlugins(sourcePath);
12
+ async getModulePlugins(sourcePath, variant) {
13
+ return this.strategy.createDevTransformPlugins(sourcePath, variant);
15
14
  }
16
- getRuntimeSpecifierMap() {
17
- return getBrowserRuntimeSpecifierMap(this.strategy.getRuntimeManifest());
15
+ getVendorEntries() {
16
+ return this.strategy.getVendorEntries();
18
17
  }
19
18
  async getVendorBundlePlugins() {
20
19
  return this.strategy.getVendorBundlePlugins();
@@ -9,7 +9,6 @@ export type HmrProcessContext = {
9
9
  ownsWatchedEntrypoint: (filePath: string) => boolean;
10
10
  isDevTransformOutputUrl: (outputUrl: string) => boolean;
11
11
  collectReactPageBuildTargets: () => Promise<ReactHmrBuildTarget[]>;
12
- hasLayoutOwnedDependencyTarget: (changedFilePath: string, requestedTargets: ReactHmrBuildTarget[]) => Promise<boolean>;
13
12
  resolveBuildTargets: (requestedTargets: ReactHmrBuildTarget[], changedFilePath: string) => Promise<ReactHmrBuildTarget[]>;
14
13
  partitionBuildTargets: (requestedTargets: ReactHmrBuildTarget[], groupedPageTargets: ReactHmrBuildTarget[]) => {
15
14
  pageTargets: ReactHmrBuildTarget[];
@@ -25,10 +24,13 @@ export type DependencyScanResult = {
25
24
  shouldAbort: boolean;
26
25
  };
27
26
  export declare function scanDependencyHits(ctx: HmrProcessContext, changedEntrypointOutput?: string): DependencyScanResult;
28
- export declare function resolveRequestedTargets(ctx: HmrProcessContext, changedEntrypointOutput: string | undefined, isLayout: boolean, isChangedPageEntrypoint: boolean, hasOwnedLayoutDependencyHit: boolean, affectedEntrypoints: Map<string, string>, hasDependencyHits: boolean): Promise<{
29
- requestedTargets: ReactHmrBuildTarget[];
30
- hasLayoutOwnedRequestedTarget: boolean;
31
- }>;
27
+ /**
28
+ * @remarks
29
+ * A changed watched entrypoint that is neither a Page nor a Layout file also refreshes the owned Pages that
30
+ * import it, so a layout it belongs to re-renders from the Page's fresh import instead of matching the
31
+ * layout by component identity.
32
+ */
33
+ export declare function resolveRequestedTargets(ctx: HmrProcessContext, changedEntrypointOutput: string | undefined, isLayout: boolean, isChangedPageEntrypoint: boolean, hasOwnedLayoutDependencyHit: boolean, affectedEntrypoints: Map<string, string>, hasDependencyHits: boolean): Promise<ReactHmrBuildTarget[]>;
32
34
  export declare function collectHmrUpdateUrls(ctx: HmrProcessContext, requestedTargets: ReactHmrBuildTarget[], pageTargets: ReactHmrBuildTarget[], nonPageTargets: ReactHmrBuildTarget[]): string[];
33
35
  export declare function buildHmrAction(requiresLayoutRefresh: boolean, updates: string[]): HmrAction;
34
36
  export declare function ensureWatchedEntrypointOwnership(ctx: HmrProcessContext, changedEntrypointOutput: string | undefined): 'continue' | 'abort';
@@ -1,4 +1,4 @@
1
- import path from 'node:path';
1
+ import { path } from '@ecopages/file-system/path';
2
2
  export function scanDependencyHits(ctx, changedEntrypointOutput) {
3
3
  const dependencyHits = ctx.getDependencyEntrypoints(ctx.resolvedFilePath);
4
4
  const affectedEntrypoints = new Map();
@@ -20,23 +20,28 @@ export function scanDependencyHits(ctx, changedEntrypointOutput) {
20
20
  const shouldAbort = affectedEntrypoints.size === 0 && !hasOwnedLayoutDependencyHit && !ctx.isLayoutFile(ctx.resolvedFilePath);
21
21
  return { affectedEntrypoints, hasOwnedLayoutDependencyHit, shouldAbort };
22
22
  }
23
+ /**
24
+ * @remarks
25
+ * A changed watched entrypoint that is neither a Page nor a Layout file also refreshes the owned Pages that
26
+ * import it, so a layout it belongs to re-renders from the Page's fresh import instead of matching the
27
+ * layout by component identity.
28
+ */
23
29
  export async function resolveRequestedTargets(ctx, changedEntrypointOutput, isLayout, isChangedPageEntrypoint, hasOwnedLayoutDependencyHit, affectedEntrypoints, hasDependencyHits) {
24
- let layoutOwnedPageTargets = [];
25
- let hasLayoutOwnedRequestedTarget = false;
26
- if (changedEntrypointOutput && !isLayout && !isChangedPageEntrypoint) {
27
- layoutOwnedPageTargets = await ctx.collectReactPageBuildTargets();
28
- hasLayoutOwnedRequestedTarget = await ctx.hasLayoutOwnedDependencyTarget(ctx.resolvedFilePath, layoutOwnedPageTargets);
30
+ if (changedEntrypointOutput) {
31
+ const changedTarget = { entrypointPath: ctx.resolvedFilePath, outputUrl: changedEntrypointOutput };
32
+ if (isLayout || isChangedPageEntrypoint) {
33
+ return [changedTarget];
34
+ }
35
+ const dependentEntrypoints = ctx.getDependencyEntrypoints(ctx.resolvedFilePath);
36
+ const dependentPageTargets = (await ctx.collectReactPageBuildTargets()).filter((target) => dependentEntrypoints.has(target.entrypointPath));
37
+ return [changedTarget, ...dependentPageTargets];
38
+ }
39
+ if (hasOwnedLayoutDependencyHit) {
40
+ return await ctx.collectReactPageBuildTargets();
29
41
  }
30
- const requestedTargets = changedEntrypointOutput
31
- ? hasLayoutOwnedRequestedTarget
32
- ? [{ entrypointPath: ctx.resolvedFilePath, outputUrl: changedEntrypointOutput }, ...layoutOwnedPageTargets]
33
- : [{ entrypointPath: ctx.resolvedFilePath, outputUrl: changedEntrypointOutput }]
34
- : hasOwnedLayoutDependencyHit
35
- ? await ctx.collectReactPageBuildTargets()
36
- : hasDependencyHits
37
- ? Array.from(affectedEntrypoints, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }))
38
- : Array.from(ctx.watchedFiles, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }));
39
- return { requestedTargets, hasLayoutOwnedRequestedTarget };
42
+ return hasDependencyHits
43
+ ? Array.from(affectedEntrypoints, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }))
44
+ : Array.from(ctx.watchedFiles, ([entrypointPath, outputUrl]) => ({ entrypointPath, outputUrl }));
40
45
  }
41
46
  export function collectHmrUpdateUrls(ctx, requestedTargets, pageTargets, nonPageTargets) {
42
47
  const updates = [];
@@ -7,15 +7,15 @@
7
7
  * @module
8
8
  */
9
9
  import { HmrStrategy, type HmrAction } from '@ecopages/core/integration';
10
- import type { EcoBuildPlugin } from '@ecopages/core/integration';
11
- import type { BrowserRuntimeManifest } from '@ecopages/core/build';
10
+ import type { DevTransformVendorEntries, EcoBuildPlugin } from '@ecopages/core/integration';
12
11
  import type { DefaultHmrContext } from '@ecopages/core/integration';
12
+ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
13
13
  import type { HmrPageMetadataCache } from './page-metadata-cache.js';
14
14
  export interface ReactHmrStrategyOptions {
15
15
  context: DefaultHmrContext;
16
16
  projectRoot?: string;
17
17
  pageMetadataCache: HmrPageMetadataCache;
18
- runtimeManifest: BrowserRuntimeManifest;
18
+ routerAdapter?: ReactRouterAdapter;
19
19
  getMdxLoaderPlugin?: () => EcoBuildPlugin;
20
20
  ownedTemplateExtensions?: string[];
21
21
  allTemplateExtensions?: string[];
@@ -31,7 +31,7 @@ export declare class ReactHmrStrategy extends HmrStrategy {
31
31
  private readonly allTemplateExtensions;
32
32
  private readonly context;
33
33
  private readonly pageMetadataCache;
34
- private readonly runtimeManifest;
34
+ private readonly routerAdapter?;
35
35
  private importNodePageModule;
36
36
  private getDevTransformPluginOptions;
37
37
  constructor(options: ReactHmrStrategyOptions);
@@ -48,14 +48,15 @@ export declare class ReactHmrStrategy extends HmrStrategy {
48
48
  private isDevTransformOutputUrl;
49
49
  private queueDevTransformOutputUpdates;
50
50
  private ownsWatchedEntrypoint;
51
- private configContainsFile;
52
- private pageModuleRequiresLayoutRefresh;
53
- private hasLayoutOwnedDependencyTarget;
54
51
  matches(filePath: string): boolean;
55
- ownsDevTransformEntrypoint(sourcePath: string): boolean;
56
- getRuntimeManifest(): BrowserRuntimeManifest;
52
+ ownsDevTransformEntrypoint(sourcePath: string, variant?: string): boolean;
53
+ /**
54
+ * Packages the generated Page and island entries import, plus the JSX runtimes of compiled React modules,
55
+ * resolved from this package.
56
+ */
57
+ getVendorEntries(): DevTransformVendorEntries;
57
58
  getVendorBundlePlugins(): Promise<readonly EcoBuildPlugin[]>;
58
- createDevTransformPlugins(sourcePath: string): Promise<EcoBuildPlugin[]>;
59
+ createDevTransformPlugins(sourcePath: string, _variant?: string): Promise<EcoBuildPlugin[]>;
59
60
  private isLayoutFile;
60
61
  private isPageEntrypoint;
61
62
  private resolveEntrypointOutputUrl;
@@ -6,17 +6,16 @@
6
6
  *
7
7
  * @module
8
8
  */
9
- import path from 'node:path';
9
+ import { path } from '@ecopages/file-system/path';
10
10
  import { HmrStrategy, HmrStrategyType } from '@ecopages/core/integration';
11
11
  import { isRegisteredScriptEntrypoint } from '@ecopages/core/integration';
12
12
  import { DEV_TRANSFORM_URL_PREFIX } from '@ecopages/core/integration';
13
13
  import { isPathInside } from '@ecopages/core/build';
14
- import { createBrowserRuntimePlugin } from '@ecopages/core/build';
15
14
  import { Logger } from '@ecopages/logger';
16
- import { createClientGraphBoundaryPlugin } from '../client-graph/boundary-plugin.js';
17
- import { someInConfigTree } from '../client-graph/component-config-traversal.js';
18
- import { getReactClientGraphAllowSpecifiers } from '../bundling/runtime-alias-map.js';
19
- import { getComponentIdentity } from '@ecopages/core';
15
+ import { createClientGraphBoundaryPlugin, createForeignBoundaryPlugin } from '../client-graph/boundary-plugin.js';
16
+ import { REACT_BOUNDARY_VARIANT } from '../client-graph/foreign-boundary-rewrite.js';
17
+ import { getReactClientGraphAllowSpecifiers } from '../bundling/bundle.js';
18
+ import { getReactBrowserPackages } from '../bundling/bootstrap-package-paths.js';
20
19
  import { buildReactDevTransformPlugins, resolveReactDeclaredModulesForEntrypoint, } from './react-hmr-dev-transform-plugins.js';
21
20
  import { buildHmrAction, collectHmrUpdateUrls, ensureWatchedEntrypointOwnership, resolveRequestedTargets, scanDependencyHits, } from './hmr-strategy-process.js';
22
21
  const appLogger = new Logger('[ReactHmrStrategy]');
@@ -31,7 +30,7 @@ export class ReactHmrStrategy extends HmrStrategy {
31
30
  allTemplateExtensions;
32
31
  context;
33
32
  pageMetadataCache;
34
- runtimeManifest;
33
+ routerAdapter;
35
34
  async importNodePageModule(entrypointPath) {
36
35
  return await this.context.importServerModule(entrypointPath);
37
36
  }
@@ -48,25 +47,27 @@ export class ReactHmrStrategy extends HmrStrategy {
48
47
  this.context = options.context;
49
48
  this.projectRoot = options.projectRoot ?? path.dirname(this.context.getSrcDir());
50
49
  this.pageMetadataCache = options.pageMetadataCache;
51
- this.runtimeManifest = options.runtimeManifest;
50
+ this.routerAdapter = options.routerAdapter;
52
51
  this.getMdxLoaderPlugin = options.getMdxLoaderPlugin;
53
52
  this.ownedTemplateExtensions = new Set(options.ownedTemplateExtensions ?? ['.tsx']);
54
53
  this.allTemplateExtensions = [...(options.allTemplateExtensions ?? ['.tsx'])].sort((a, b) => b.length - a.length);
55
54
  }
56
55
  getBuildPlugins(declaredModules) {
57
- const allowSpecifiers = getReactClientGraphAllowSpecifiers(this.runtimeManifest.assets.map((asset) => asset.specifier));
58
- const runtimeRewritePlugin = createBrowserRuntimePlugin({
59
- name: 'react-hmr-runtime-import-rewrite',
60
- manifest: this.runtimeManifest,
61
- });
62
56
  return [
63
57
  createClientGraphBoundaryPlugin({
64
58
  projectRoot: this.projectRoot,
65
59
  absWorkingDir: this.projectRoot,
66
- alwaysAllowSpecifiers: allowSpecifiers,
60
+ alwaysAllowSpecifiers: getReactClientGraphAllowSpecifiers(this.routerAdapter),
67
61
  declaredModules,
68
62
  }),
69
- ...(runtimeRewritePlugin ? [runtimeRewritePlugin] : []),
63
+ createForeignBoundaryPlugin({
64
+ projectRoot: this.projectRoot,
65
+ isForeignFile: (filePath) => {
66
+ const templateExtension = this.resolveTemplateExtension(filePath);
67
+ return templateExtension !== undefined && !this.ownedTemplateExtensions.has(templateExtension);
68
+ },
69
+ isSharedFile: (filePath) => !this.isReactEntrypoint(filePath),
70
+ }),
70
71
  ];
71
72
  }
72
73
  isReactEntrypoint(filePath) {
@@ -113,33 +114,6 @@ export class ReactHmrStrategy extends HmrStrategy {
113
114
  ownsWatchedEntrypoint(filePath) {
114
115
  return this.pageMetadataCache.ownsEntrypoint(filePath);
115
116
  }
116
- configContainsFile(config, filePath) {
117
- const resolvedFilePath = path.resolve(filePath);
118
- return someInConfigTree(config, (node) => {
119
- const identity = getComponentIdentity(node);
120
- if (!identity?.file) {
121
- return false;
122
- }
123
- return path.resolve(identity.file) === resolvedFilePath;
124
- });
125
- }
126
- pageModuleRequiresLayoutRefresh(pageModule, filePath) {
127
- return [pageModule.default?.config, pageModule.config].some((config) => {
128
- return (config?.layouts ?? []).some((layout) => this.configContainsFile(layout?.config, filePath));
129
- });
130
- }
131
- async hasLayoutOwnedDependencyTarget(changedFilePath, requestedTargets) {
132
- for (const target of requestedTargets) {
133
- if (!this.isPageEntrypoint(target.entrypointPath)) {
134
- continue;
135
- }
136
- const pageModule = await this.importNodePageModule(target.entrypointPath);
137
- if (this.pageModuleRequiresLayoutRefresh(pageModule, changedFilePath)) {
138
- return true;
139
- }
140
- }
141
- return false;
142
- }
143
117
  matches(filePath) {
144
118
  const watchedFiles = this.context.getWatchedFiles();
145
119
  const resolvedFilePath = path.resolve(filePath);
@@ -168,19 +142,29 @@ export class ReactHmrStrategy extends HmrStrategy {
168
142
  }
169
143
  return this.isReactEntrypoint(filePath);
170
144
  }
171
- ownsDevTransformEntrypoint(sourcePath) {
145
+ ownsDevTransformEntrypoint(sourcePath, variant) {
146
+ if (variant === REACT_BOUNDARY_VARIANT) {
147
+ return isPathInside(sourcePath, this.context.getSrcDir());
148
+ }
172
149
  if (!this.isReactEntrypoint(sourcePath)) {
173
150
  return false;
174
151
  }
175
152
  return isPathInside(sourcePath, this.context.getSrcDir());
176
153
  }
177
- getRuntimeManifest() {
178
- return this.runtimeManifest;
154
+ /**
155
+ * Packages the generated Page and island entries import, plus the JSX runtimes of compiled React modules,
156
+ * resolved from this package.
157
+ */
158
+ getVendorEntries() {
159
+ return {
160
+ resolveFrom: path.dirname(path.fromFileUrl(import.meta.url)),
161
+ specifiers: getReactBrowserPackages(this.routerAdapter),
162
+ };
179
163
  }
180
164
  async getVendorBundlePlugins() {
181
165
  return this.getBuildPlugins();
182
166
  }
183
- async createDevTransformPlugins(sourcePath) {
167
+ async createDevTransformPlugins(sourcePath, _variant) {
184
168
  const shouldResolveDeclaredModules = this.isPageEntrypoint(sourcePath) || sourcePath.endsWith('.mdx');
185
169
  const declaredModules = shouldResolveDeclaredModules
186
170
  ? await resolveReactDeclaredModulesForEntrypoint(this.getDevTransformPluginOptions(), sourcePath)
@@ -250,7 +234,6 @@ export class ReactHmrStrategy extends HmrStrategy {
250
234
  ownsWatchedEntrypoint: (filePath) => this.ownsWatchedEntrypoint(filePath),
251
235
  isDevTransformOutputUrl: (outputUrl) => this.isDevTransformOutputUrl(outputUrl),
252
236
  collectReactPageBuildTargets: () => this.collectReactPageBuildTargets(),
253
- hasLayoutOwnedDependencyTarget: (changedFilePath, requestedTargets) => this.hasLayoutOwnedDependencyTarget(changedFilePath, requestedTargets),
254
237
  resolveBuildTargets: (requestedTargets, changedFilePath) => this.resolveBuildTargets(requestedTargets, changedFilePath),
255
238
  partitionBuildTargets: (requestedTargets, groupedPageTargets) => this.partitionBuildTargets(requestedTargets, groupedPageTargets),
256
239
  queueDevTransformOutputUpdates: (targets, requestedOutputUrls, updates) => this.queueDevTransformOutputUpdates(targets, requestedOutputUrls, updates),
@@ -283,14 +266,10 @@ export class ReactHmrStrategy extends HmrStrategy {
283
266
  appLogger.debug(`Dependency hits found but none map to React-owned watched entrypoints`);
284
267
  return { type: 'none' };
285
268
  }
286
- const { requestedTargets, hasLayoutOwnedRequestedTarget: initialLayoutOwned } = await resolveRequestedTargets(processContext, changedEntrypointOutput, isLayout, isChangedPageEntrypoint, dependencyScan.hasOwnedLayoutDependencyHit, dependencyScan.affectedEntrypoints, dependencyHits.size > 0);
269
+ const requestedTargets = await resolveRequestedTargets(processContext, changedEntrypointOutput, isLayout, isChangedPageEntrypoint, dependencyScan.hasOwnedLayoutDependencyHit, dependencyScan.affectedEntrypoints, dependencyHits.size > 0);
287
270
  const groupedPageTargets = await processContext.resolveBuildTargets(requestedTargets, resolvedFilePath);
288
271
  const { pageTargets, nonPageTargets } = processContext.partitionBuildTargets(requestedTargets, groupedPageTargets);
289
- let hasLayoutOwnedRequestedTarget = initialLayoutOwned;
290
- if (!changedEntrypointOutput) {
291
- hasLayoutOwnedRequestedTarget = await processContext.hasLayoutOwnedDependencyTarget(resolvedFilePath, requestedTargets);
292
- }
293
- const requiresLayoutRefresh = isLayout || dependencyScan.hasOwnedLayoutDependencyHit || hasLayoutOwnedRequestedTarget;
272
+ const requiresLayoutRefresh = isLayout || dependencyScan.hasOwnedLayoutDependencyHit;
294
273
  const updates = collectHmrUpdateUrls(processContext, requestedTargets, pageTargets, nonPageTargets);
295
274
  if (requiresLayoutRefresh) {
296
275
  appLogger.debug(`Layout update detected, sending layout-update event`);
@@ -1,4 +1,4 @@
1
- import path from 'node:path';
1
+ import { path } from '@ecopages/file-system/path';
2
2
  /**
3
3
  * React-only cache for page metadata that HMR rebuilds need during development.
4
4
  *
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The component type a React module renders in place of an Eco Component another Integration owns.
3
+ *
4
+ * @remarks
5
+ * The React client graph rewrites each import of such a Component to {@link foreignBoundary}, so the boundary is a
6
+ * property of how React modules are built and the Eco browser factory renders inline for every caller. The
7
+ * boundary keeps the Component's server HTML instead of calling its `render`, which returns output React cannot
8
+ * render, such as a Lit `TemplateResult`.
9
+ *
10
+ * @module
11
+ */
12
+ /**
13
+ * Returns the component type React renders for `value`: a boundary when it is an Eco Component another
14
+ * Integration owns, `value` itself otherwise.
15
+ *
16
+ * @remarks
17
+ * The boundary is keyed by its subtree key, so new props re-mount it and read the matching server HTML. It passes
18
+ * the same `dangerouslySetInnerHTML` object and the same `ref` on every render, because React compares a custom
19
+ * element's props by reference and a new object would rewrite the live DOM inside. The object is empty: a
20
+ * hydrating boundary keeps the DOM it finds, and a created one is filled by {@link fillBoundary} once React has
21
+ * attached it, so its declarative shadow roots survive; see the Islands and hydration developer page.
22
+ *
23
+ * One boundary type per Component keeps React from re-mounting it on a parent render.
24
+ */
25
+ export declare function foreignBoundary<T>(value: T): T;
26
+ /**
27
+ * Wraps a namespace import of a module another Integration owns, so `ns.Component` is its boundary.
28
+ */
29
+ export declare function foreignBoundaryNamespace<T extends object>(namespace: T): T;
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The component type a React module renders in place of an Eco Component another Integration owns.
3
+ *
4
+ * @remarks
5
+ * The React client graph rewrites each import of such a Component to {@link foreignBoundary}, so the boundary is a
6
+ * property of how React modules are built and the Eco browser factory renders inline for every caller. The
7
+ * boundary keeps the Component's server HTML instead of calling its `render`, which returns output React cannot
8
+ * render, such as a Lit `TemplateResult`.
9
+ *
10
+ * @module
11
+ */
12
+ import { createElement, useState } from 'react';
13
+ import { isProductionRuntime } from '@ecopages/core';
14
+ import { REACT_PLUGIN_NAME } from '../../plugin/react.constants.js';
15
+ import { FOREIGN_SUBTREE_DISPLAY, FOREIGN_SUBTREE_KEY_ATTRIBUTE, FOREIGN_SUBTREE_TAG, getForeignSubtreeKey, } from '../foreign-subtree.js';
16
+ /**
17
+ * Returns the server HTML of the Foreign Subtree named `key`.
18
+ *
19
+ * @remarks
20
+ * Every mount reads it, hydration included, where React keeps the existing DOM whatever was read. A client
21
+ * navigation publishes the fetched document as `page.document` before it renders the next Page, and that document
22
+ * comes first, and a direct HMR update publishes the document it fetched the same way; otherwise the live document
23
+ * holds it. Without either, the boundary stays empty and warns.
24
+ */
25
+ function readServerHtml(key) {
26
+ const selector = `${FOREIGN_SUBTREE_TAG}[${FOREIGN_SUBTREE_KEY_ATTRIBUTE}="${key}"]`;
27
+ const navigationDocument = window.__ECO_PAGES__?.page?.document;
28
+ for (const source of [navigationDocument, document]) {
29
+ const boundary = source?.querySelector(selector);
30
+ if (boundary)
31
+ return boundary.innerHTML;
32
+ }
33
+ return '';
34
+ }
35
+ /**
36
+ * Gives a freshly created boundary its server HTML with the declarative shadow roots in it.
37
+ *
38
+ * @remarks
39
+ * React creates the boundary empty, and a boundary that hydrates already holds its HTML, so only an empty one is
40
+ * filled. `setHTMLUnsafe()` parses declarative shadow roots, where React's `innerHTML` would leave them inert
41
+ * templates. A custom element in that HTML, Lit's included, upgrades with its server-rendered shadow root and can
42
+ * hydrate it instead of rendering again. A browser without `setHTMLUnsafe()` falls back to `innerHTML`, so a
43
+ * custom element there renders itself on the client.
44
+ */
45
+ function fillBoundary(boundary, html) {
46
+ if (!boundary || boundary.hasChildNodes() || !html)
47
+ return;
48
+ if (typeof boundary.setHTMLUnsafe === 'function') {
49
+ boundary.setHTMLUnsafe(html);
50
+ }
51
+ else {
52
+ boundary.innerHTML = html;
53
+ }
54
+ }
55
+ const BOUNDARY_STYLE = { display: FOREIGN_SUBTREE_DISPLAY };
56
+ const warnedKeys = new Set();
57
+ /**
58
+ * Warns once per key, outside production, that a boundary found no server HTML and stays empty.
59
+ *
60
+ * @remarks
61
+ * The supported path is a Foreign Subtree the server rendered inside the hydrating tree, with the props it had
62
+ * there. A foreign Component that first renders on the client, or a client-only prop change, has no server HTML
63
+ * to keep, and the boundary cannot render the Component itself.
64
+ */
65
+ function warnEmptyBoundary(key, component) {
66
+ if (isProductionRuntime() || warnedKeys.has(key))
67
+ return;
68
+ warnedKeys.add(key);
69
+ const file = component.config?.identity?.file ?? component.config?.identity?.id ?? 'a foreign Component';
70
+ console.warn(`[ecopages] The foreign Component ${file} has no server HTML for the subtree "${key}", so it renders empty. ` +
71
+ `A foreign Component renders in React only where the server rendered it with the same props.`);
72
+ }
73
+ function ForeignSubtree({ subtreeKey, component }) {
74
+ const [boundary] = useState(() => {
75
+ const html = readServerHtml(subtreeKey);
76
+ if (!html)
77
+ warnEmptyBoundary(subtreeKey, component);
78
+ return { emptyHtml: { __html: '' }, ref: (element) => fillBoundary(element, html) };
79
+ });
80
+ return createElement(FOREIGN_SUBTREE_TAG, {
81
+ [FOREIGN_SUBTREE_KEY_ATTRIBUTE]: subtreeKey,
82
+ style: BOUNDARY_STYLE,
83
+ suppressHydrationWarning: true,
84
+ dangerouslySetInnerHTML: boundary.emptyHtml,
85
+ ref: boundary.ref,
86
+ });
87
+ }
88
+ const boundaries = new WeakMap();
89
+ function isForeignEcoComponent(value) {
90
+ if (typeof value !== 'function')
91
+ return false;
92
+ const config = value.config;
93
+ return config?.identity !== undefined && (config.integration ?? config.identity.integration) !== REACT_PLUGIN_NAME;
94
+ }
95
+ /**
96
+ * Returns the component type React renders for `value`: a boundary when it is an Eco Component another
97
+ * Integration owns, `value` itself otherwise.
98
+ *
99
+ * @remarks
100
+ * The boundary is keyed by its subtree key, so new props re-mount it and read the matching server HTML. It passes
101
+ * the same `dangerouslySetInnerHTML` object and the same `ref` on every render, because React compares a custom
102
+ * element's props by reference and a new object would rewrite the live DOM inside. The object is empty: a
103
+ * hydrating boundary keeps the DOM it finds, and a created one is filled by {@link fillBoundary} once React has
104
+ * attached it, so its declarative shadow roots survive; see the Islands and hydration developer page.
105
+ *
106
+ * One boundary type per Component keeps React from re-mounting it on a parent render.
107
+ */
108
+ export function foreignBoundary(value) {
109
+ if (!isForeignEcoComponent(value))
110
+ return value;
111
+ let boundary = boundaries.get(value);
112
+ if (!boundary) {
113
+ boundary = (props) => {
114
+ const subtreeKey = getForeignSubtreeKey(value, props);
115
+ return createElement(ForeignSubtree, { key: subtreeKey, subtreeKey, component: value });
116
+ };
117
+ boundaries.set(value, boundary);
118
+ }
119
+ return boundary;
120
+ }
121
+ /**
122
+ * Wraps a namespace import of a module another Integration owns, so `ns.Component` is its boundary.
123
+ */
124
+ export function foreignBoundaryNamespace(namespace) {
125
+ return new Proxy(namespace, {
126
+ get: (target, property, receiver) => foreignBoundary(Reflect.get(target, property, receiver)),
127
+ });
128
+ }
@@ -2,9 +2,8 @@
2
2
  * Browser-side React Island Host lifecycle.
3
3
  *
4
4
  * @remarks
5
- * This module intentionally receives React's browser runtime as a value. The
6
- * server entry compiler can therefore keep the application's React and
7
- * ReactDOM imports external while bundling this framework-owned lifecycle.
5
+ * The generated Island Host entry imports React and passes its runtime in as a value, so this module itself has no
6
+ * React import.
8
7
  */
9
8
  export type IslandComponent = (props: Record<string, unknown>) => unknown;
10
9
  export type IslandReactRuntime = {
@@ -26,7 +25,7 @@ export type IslandHydrationRuntime = {
26
25
  /** Island entries by HMR module path, then by script id. One file can declare several islands. */
27
26
  hmrEntries?: Map<string, Map<string, IslandHydrationOptions>>;
28
27
  };
29
- /** Configuration for one compiled React Island Host entry. */
28
+ /** Configuration for one generated React Island Host entry. */
30
29
  export type IslandHydrationOptions = {
31
30
  targetSelector: string;
32
31
  componentModule: Record<string, unknown>;
@@ -2,9 +2,8 @@
2
2
  * Browser-side React Island Host lifecycle.
3
3
  *
4
4
  * @remarks
5
- * This module intentionally receives React's browser runtime as a value. The
6
- * server entry compiler can therefore keep the application's React and
7
- * ReactDOM imports external while bundling this framework-owned lifecycle.
5
+ * The generated Island Host entry imports React and passes its runtime in as a value, so this module itself has no
6
+ * React import.
8
7
  */
9
8
  /**
10
9
  * Returns the shared page runtime used by all React Island Host entries.
@@ -117,7 +116,7 @@ function IslandLifecycle({ target, runtime, Component, props }) {
117
116
  *
118
117
  * @remarks
119
118
  * Decodes the format core's `encodeIslandProps` writes in `islands/island-host.ts` (base64 of UTF-8 JSON). It is
120
- * inlined because this module compiles into a self-contained browser script that cannot import core.
119
+ * inlined so this module does not pull core's server-side island code into the browser.
121
120
  */
122
121
  function readProps(target) {
123
122
  try {