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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -1
  2. package/package.json +4 -4
  3. package/src/app/client-only.js +13 -17
  4. package/src/app/dynamic.js +7 -10
  5. package/src/app/dynamic.test.browser.js +27 -29
  6. package/src/bundling/bootstrap-package-paths.js +5 -6
  7. package/src/bundling/bundle.js +115 -114
  8. package/src/bundling/discover-layout-runtime-modules.js +166 -155
  9. package/src/bundling/runtime-alias-map.d.ts +4 -1
  10. package/src/bundling/runtime-alias-map.js +107 -95
  11. package/src/bundling/runtime-bundle.js +250 -274
  12. package/src/bundling/runtime-interop-plugin.js +31 -35
  13. package/src/bundling/runtime-mode.js +10 -5
  14. package/src/bundling/runtime-modules.js +46 -35
  15. package/src/client-graph/ast-transform.js +415 -305
  16. package/src/client-graph/boundary-cache.js +146 -104
  17. package/src/client-graph/boundary-plugin.js +122 -104
  18. package/src/client-graph/component-config-traversal.js +70 -49
  19. package/src/client-graph/declared-modules.js +63 -41
  20. package/src/client-graph/reachability-analyzer.js +506 -313
  21. package/src/client-graph/specifier-classification.js +209 -141
  22. package/src/contracts/router-adapter.js +6 -0
  23. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  24. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  25. package/src/hmr/hmr-scripts.js +22 -9
  26. package/src/hmr/hmr-strategy.d.ts +12 -181
  27. package/src/hmr/hmr-strategy.js +321 -650
  28. package/src/hmr/page-metadata-cache.js +43 -40
  29. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
  30. package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
  31. package/src/hydration/assert-no-bare-ecopages-imports.js +6 -6
  32. package/src/hydration/bootstrap-imports.js +30 -20
  33. package/src/hydration/hydration-asset.js +216 -213
  34. package/src/hydration/hydration-scripts.d.ts +4 -0
  35. package/src/hydration/hydration-scripts.js +199 -66
  36. package/src/hydration/hydration-scripts.test.browser.js +163 -168
  37. package/src/hydration/page-data-manifest.js +89 -45
  38. package/src/hydration/page-data-reader.js +45 -32
  39. package/src/hydration/page-payload.js +101 -99
  40. package/src/hydration/serialize-page-data-script.js +27 -28
  41. package/src/mdx/mdx-config-dependency.js +108 -112
  42. package/src/mdx/mdx-loader-plugin.js +7 -10
  43. package/src/page/page-module.js +72 -66
  44. package/src/plugin/react.constants.js +1 -4
  45. package/src/plugin/react.plugin.d.ts +1 -0
  46. package/src/plugin/react.plugin.js +227 -216
  47. package/src/plugin/react.types.js +1 -0
  48. package/src/render/component-ownership.js +42 -18
  49. package/src/render/component-ssr.js +168 -190
  50. package/src/render/eco-embed.js +8 -10
  51. package/src/render/errors.js +21 -16
  52. package/src/render/html-boundary.js +55 -51
  53. package/src/render/layout-compose.js +122 -94
  54. package/src/render/react-renderer.js +433 -468
  55. package/src/render/react-runtime.js +25 -20
  56. package/src/render/unified-layout-composition.js +74 -85
  57. package/src/runtime/use-sync-external-store-with-selector.js +52 -54
@@ -7,6 +7,7 @@
7
7
  * @module
8
8
  */
9
9
  import { HmrStrategy, type HmrAction } from '@ecopages/core/hmr/hmr-strategy';
10
+ import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
10
11
  import type { BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
11
12
  import type { DefaultHmrContext } from '@ecopages/core';
12
13
  import type { CompileOptions } from '@mdx-js/mdx';
@@ -29,76 +30,22 @@ export interface ReactHmrStrategyOptions {
29
30
  }
30
31
  /**
31
32
  * Strategy for handling React component HMR updates.
32
- *
33
- * This strategy provides React-specific HMR handling by rebuilding entrypoints
34
- * and injecting HMR acceptance handlers that trigger module invalidation.
35
- *
36
- * The processing steps are:
37
- * 1. Check if any React entrypoints are registered
38
- * 2. Rebuild all React entrypoints (the changed file could be a dependency)
39
- * 3. Rebuild browser output through the shared browser bundle service while
40
- * preserving React-specific runtime aliases and graph policy
41
- * 4. Read page config metadata through the shared server-module loading path
42
- * 5. Inject HMR acceptance handler
43
- * 6. Broadcast update events for each rebuilt entrypoint
44
- *
45
- * @remarks
46
- * This strategy has higher priority than generic JsHmrStrategy, allowing it
47
- * to handle React files specially while falling back to generic handling for
48
- * non-React files.
49
- *
50
- * Future enhancement: Track dependencies using Bun's transpiler API to only
51
- * rebuild affected entrypoints instead of all of them.
52
- *
53
- * @see https://bun.sh/docs/runtime/transpiler
54
- *
55
- * @example
56
- * ```typescript
57
- * const context = {
58
- * getWatchedFiles: () => watchedFilesMap,
59
- * getDistDir: () => '/path/to/dist/_hmr',
60
- * getPlugins: () => [],
61
- * getSrcDir: () => '/path/to/src',
62
- * getLayoutsDir: () => '/path/to/src/layouts'
63
- * };
64
- * const strategy = new ReactHmrStrategy({
65
- * context,
66
- * pageMetadataCache,
67
- * runtimeManifest
68
- * });
69
- * ```
70
33
  */
71
34
  export declare class ReactHmrStrategy extends HmrStrategy {
72
35
  readonly type: 100;
73
36
  private mdxCompilerOptions?;
74
37
  private readonly ownedTemplateExtensions;
75
38
  private readonly allTemplateExtensions;
76
- private importNodePageModule;
77
- /**
78
- * Creates a new React HMR strategy instance.
79
- *
80
- * @param options - React HMR runtime services and behavior flags.
81
- */
82
- private context;
83
- private pageMetadataCache;
39
+ private readonly context;
40
+ private readonly pageMetadataCache;
84
41
  private readonly runtimeManifest;
85
42
  private readonly clientGraphBoundaryCache;
43
+ private importNodePageModule;
44
+ private getDevTransformPluginOptions;
86
45
  constructor(options: ReactHmrStrategyOptions);
87
- /**
88
- * Returns build plugins for React HMR bundling.
89
- *
90
- * Includes the client graph boundary plugin to prevent undeclared imports
91
- * (including `node:*`) from breaking the browser bundle.
92
- *
93
- * @remarks
94
- * HMR builds receive the React runtime manifest and rewrite manifest-owned
95
- * runtime imports to concrete asset URLs before module resolution.
96
- */
97
46
  private getBuildPlugins;
98
47
  private isReactEntrypoint;
99
48
  /**
100
- * Returns true when a route file uses a compound extension like `page.foo.tsx`.
101
- *
102
49
  * @remarks
103
50
  * React integration owns plain `.tsx` route templates. Compound extensions in
104
51
  * pages/layouts are integration-specific route templates and should not be
@@ -106,138 +53,22 @@ export declare class ReactHmrStrategy extends HmrStrategy {
106
53
  */
107
54
  private isRouteTemplate;
108
55
  private resolveTemplateExtension;
56
+ private isDevTransformOutputUrl;
57
+ private queueDevTransformOutputUpdates;
109
58
  private ownsWatchedEntrypoint;
110
59
  private configContainsFile;
111
60
  private pageModuleRequiresLayoutRefresh;
112
61
  private hasLayoutOwnedDependencyTarget;
113
- /**
114
- * Determines if the file is a React/MDX entrypoint that's registered for HMR.
115
- *
116
- * Uses a three-way decision strategy for selective invalidation:
117
- * 1. If the file is a watched entrypoint, check if React owns it
118
- * 2. If the file is a dependency of watched entrypoints (via dependency graph),
119
- * check if any affected entrypoints are React-owned. Returns false if hits
120
- * exist but none are owned (prevents unnecessary rebuilds).
121
- * 3. Otherwise, check if the file itself is a React entrypoint template
122
- *
123
- * @param filePath - Absolute path to the changed file
124
- * @returns True if this file should trigger React HMR rebuilds
125
- */
126
62
  matches(filePath: string): boolean;
127
- canEmitEntrypoint(entrypointPath: string): boolean;
128
- emitEntrypoint(entrypointPath: string, _outputPath: string): Promise<void>;
129
- /**
130
- * Checks if a file is a layout file.
131
- *
132
- * Layout files require special HMR handling because they wrap multiple pages and affect
133
- * the entire page structure. When a layout changes, we trigger a 'layout-update' event
134
- * instead of a regular 'update' event, which instructs the browser to perform a full
135
- * page reload (or clear cache and re-render) rather than attempting module-level HMR.
136
- *
137
- * @param filePath - Absolute path to the file
138
- * @returns True if the file is in the layouts directory
139
- */
63
+ ownsDevTransformEntrypoint(sourcePath: string): boolean;
64
+ getRuntimeManifest(): BrowserRuntimeManifest;
65
+ getVendorBundlePlugins(): Promise<readonly EcoBuildPlugin[]>;
66
+ createDevTransformPlugins(sourcePath: string): Promise<EcoBuildPlugin[]>;
140
67
  private isLayoutFile;
141
68
  private isPageEntrypoint;
142
- private getEntrypointOutput;
143
- private getRolldownEntryKey;
144
- private getTempFileBasename;
69
+ private resolveEntrypointOutputUrl;
145
70
  private collectReactPageBuildTargets;
146
- /**
147
- * Expands one HMR request into the full React page build cohort when needed.
148
- *
149
- * @remarks
150
- * Page and layout changes need one shared rebuild pass so sibling routes keep
151
- * a consistent client module graph. Non-page changes that do not touch a page
152
- * cohort can stay scoped to the originally requested targets.
153
- */
154
71
  private resolveBuildTargets;
155
72
  private partitionBuildTargets;
156
- /**
157
- * Processes a React file change by rebuilding affected React entrypoints.
158
- *
159
- * Uses a three-way decision strategy for selective invalidation:
160
- * 1. Changed file is a watched entrypoint: rebuild only that entrypoint
161
- * 2. Dependency graph has hits: rebuild only affected React-owned entrypoints.
162
- * If hits exist but none map to React-owned entrypoints, return 'none' to
163
- * prevent unnecessary rebuilds.
164
- * 3. Dependency graph miss: fall back to rebuilding all watched entrypoints
165
- *
166
- * For layout files, broadcasts a 'layout-update' event to trigger full page reload.
167
- * For regular components/pages, broadcasts 'update' events for module-level HMR.
168
- *
169
- * @param _filePath - Absolute path to the changed file
170
- * @returns Action to broadcast update events (layout-update for layouts, update for components)
171
- */
172
73
  process(_filePath: string): Promise<HmrAction>;
173
- /**
174
- * Clears stale HMR output once per outdir before any rebuild pass in `process()`.
175
- *
176
- * @remarks
177
- * Grouped page builds share `getDistDir()`; single page and non-page targets use
178
- * per-entrypoint temp directories. Clearing here avoids redundant work when both
179
- * page and non-page targets land in the same outdir.
180
- */
181
- private clearOutdirsForTargets;
182
- private resolveDeclaredModulesForEntrypoint;
183
- private collectDeclaredModulesForTargets;
184
- private buildPluginsForDeclaredModules;
185
- private recordBuildDependencyGraph;
186
- /**
187
- * Bundles a single React/MDX entrypoint with HMR support.
188
- *
189
- * After successful bundling, populates the entrypoint dependency graph with
190
- * the build's dependency metadata. This enables selective invalidation on
191
- * subsequent file changes, so only entrypoints affected by a changed
192
- * dependency are rebuilt.
193
- *
194
- * @param entrypointPath - Absolute path to the source file
195
- * @param outputUrl - URL path for the bundled file
196
- * @returns True if bundling was successful
197
- */
198
- private bundleReactEntrypoint;
199
- /**
200
- * Bundles multiple React/MDX entrypoints in a single build pass.
201
- *
202
- * Uses code splitting to share common dependencies across entrypoints.
203
- * After successful bundling, populates the entrypoint dependency graph with
204
- * the build's dependency metadata for selective invalidation.
205
- *
206
- * @param entrypoints - Array of entrypoint paths and their output URLs
207
- * @returns Array of output URLs that were successfully built
208
- */
209
- private bundleReactEntrypoints;
210
- private bundleReactBuildTargets;
211
- private resolveTempOutputPath;
212
- /**
213
- * Clears stale HMR output from a directory before a rebuild.
214
- *
215
- * Only removes:
216
- * - `*.tmp.js` files (the per-build bundler output the strategy owns)
217
- * - the `chunks/` subdirectory (the bundler's splitting target)
218
- *
219
- * The HMR runtime script (`_hmr_runtime.js`) and any user-authored
220
- * assets in the outdir are preserved. This is the minimal set of
221
- * files that, if left from a previous build, can cause the bundler
222
- * to emit `ENOENT` for chunk references that point to entrypoints
223
- * whose hash has since changed.
224
- */
225
- private clearHmrOutdir;
226
- /**
227
- * Encodes dynamic route segments (brackets) in file paths.
228
- * Converts `[slug]` to `_slug_` to avoid filesystem issues.
229
- */
230
- private encodeDynamicSegments;
231
- private rewriteChunkImportUrls;
232
- private isMissingTempOutputError;
233
- /**
234
- * Processes bundled output and injects the React HMR handler.
235
- * Writes to temp file first, then renames atomically to avoid conflicts.
236
- *
237
- * @param tempPath - Path to the temporary bundled file
238
- * @param finalPath - Final destination path
239
- * @param url - URL path for logging
240
- * @returns True if processing was successful
241
- */
242
- private processOutput;
243
74
  }