@ecopages/react 0.6.1 → 0.7.1

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
@@ -1,11 +1,12 @@
1
1
  import type { PageHydrationOptions } from './page-hydration.js';
2
+ type PageData = {
3
+ moduleUrl?: string;
4
+ props: Record<string, unknown>;
5
+ };
6
+ type PageDataReader = (options: PageHydrationOptions, source?: Pick<Document, 'getElementById'>) => PageData;
7
+ type PageStateSetter = (options: PageHydrationOptions, pageData: PageData) => void;
2
8
  /**
3
9
  * Imports and applies one HMR page update.
4
10
  */
5
- export declare function handlePageHmr(options: PageHydrationOptions, newUrl: string, generation: number, readPageData: (options: PageHydrationOptions) => {
6
- moduleUrl?: string;
7
- props: Record<string, unknown>;
8
- }, setPageState: (options: PageHydrationOptions, pageData: {
9
- moduleUrl?: string;
10
- props: Record<string, unknown>;
11
- }) => void, getPageDataFromDocument: (options: PageHydrationOptions) => Record<string, unknown>): Promise<void>;
11
+ export declare function handlePageHmr(options: PageHydrationOptions, newUrl: string, generation: number, readPageData: PageDataReader, setPageState: PageStateSetter): Promise<void>;
12
+ export {};
@@ -1,41 +1,84 @@
1
1
  import { resolvePageComponent } from './page-hydration-module.js';
2
+ /**
3
+ * Numbers the updates so the newest one wins.
4
+ *
5
+ * @remarks
6
+ * An update awaits an import and, without a router, a fetch, and the HMR client does not queue the next message.
7
+ * Two saves in a row can finish out of order; an update that finds a newer one started drops itself.
8
+ */
9
+ let latestUpdate = 0;
2
10
  function getRuntime() {
3
11
  return (window.__ECO_PAGES__ ??= {});
4
12
  }
5
13
  function isCurrentMountGeneration(generation) {
6
14
  return (getRuntime().react?.mountGeneration ?? 0) === generation;
7
15
  }
16
+ /**
17
+ * @remarks
18
+ * A layout module has one URL, so an unchanged layout is the same function in both page versions.
19
+ */
20
+ function haveSameLayouts(current, next) {
21
+ return current.length === next.length && current.every((layout, index) => layout === next[index]);
22
+ }
8
23
  async function applyRouterHmrUpdate(options, newUrl, currentPage, nextPage) {
9
24
  if (!options.hasRouter || getRuntime().navigation?.getOwnerState?.().owner !== 'react-router') {
10
25
  return false;
11
26
  }
12
- const currentLayoutStack = options.hmr.getLayoutStack?.(currentPage) ?? '';
13
- const nextLayoutStack = options.hmr.getLayoutStack?.(nextPage) ?? '';
27
+ const currentLayouts = options.hmr.getLayouts?.(currentPage) ?? [];
28
+ const nextLayouts = options.hmr.getLayouts?.(nextPage) ?? [];
14
29
  await getRuntime().navigation?.reloadCurrentPage?.({
15
- clearCache: currentLayoutStack !== nextLayoutStack,
30
+ clearCache: !haveSameLayouts(currentLayouts, nextLayouts),
16
31
  moduleUrl: newUrl,
17
32
  source: 'react-router',
18
33
  });
19
34
  console.log(`[ecopages] ${options.isMdx ? 'MDX' : 'React'} component updated via router`);
20
35
  return true;
21
36
  }
22
- function applyDirectHmrRender(options, nextPage, nextProps, readPageData, setPageState, generation) {
37
+ /**
38
+ * Fetches the current URL and parses it, so a direct re-render has the server HTML of its Foreign Subtrees.
39
+ *
40
+ * @remarks
41
+ * A direct update has no router to refetch the document. The Foreign Subtree boundaries of the edited Page read
42
+ * their server HTML from it: an edit can change a Foreign Child's props, so the boundary has no HTML in the live
43
+ * document, and the live boundary of a hydrated custom element no longer holds its declarative shadow root. The
44
+ * parsed document keeps the `<template shadowrootmode>` of each, as a client navigation's does. A response that is
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`
47
+ * returns and the live `__ECO_PAGE_DATA__` still holds the old values.
48
+ */
49
+ async function fetchCurrentDocument() {
50
+ const response = await fetch(window.location.href, { headers: { accept: 'text/html' }, cache: 'no-store' });
51
+ if (!response.ok) {
52
+ throw new Error(`The server answered ${response.status} for ${window.location.pathname}`);
53
+ }
54
+ return new DOMParser().parseFromString(await response.text(), 'text/html');
55
+ }
56
+ async function applyDirectHmrRender(options, nextPage, readPageData, setPageState, generation, isSuperseded) {
57
+ if (!getRuntime().react?.pageRoot || !isCurrentMountGeneration(generation))
58
+ return;
59
+ const fetchedDocument = await fetchCurrentDocument();
23
60
  const activeRoot = getRuntime().react?.pageRoot ?? null;
24
- if (!activeRoot || !isCurrentMountGeneration(generation))
61
+ if (!activeRoot || !isCurrentMountGeneration(generation) || isSuperseded())
25
62
  return;
26
- setPageState(options, readPageData(options));
27
- activeRoot.render(options.createTree(nextPage, nextProps));
63
+ const pageData = readPageData(options, fetchedDocument);
64
+ setPageState(options, pageData);
65
+ const runtime = getRuntime();
66
+ if (runtime.page)
67
+ runtime.page.document = fetchedDocument;
68
+ activeRoot.render(options.createTree(nextPage, pageData.props));
28
69
  console.log(`[ecopages] ${options.isMdx ? 'MDX' : 'React'} component updated`);
29
70
  }
30
71
  /**
31
72
  * Imports and applies one HMR page update.
32
73
  */
33
- export async function handlePageHmr(options, newUrl, generation, readPageData, setPageState, getPageDataFromDocument) {
74
+ export async function handlePageHmr(options, newUrl, generation, readPageData, setPageState) {
34
75
  if (!options.hmr || !isCurrentMountGeneration(generation))
35
76
  return;
77
+ const update = ++latestUpdate;
78
+ const isSuperseded = () => update !== latestUpdate;
36
79
  try {
37
80
  const newModule = (await import(/* @vite-ignore */ newUrl));
38
- if (!isCurrentMountGeneration(generation))
81
+ if (!isCurrentMountGeneration(generation) || isSuperseded())
39
82
  return;
40
83
  const nextPage = resolvePageComponent(newModule, options.isMdx, options.normalizePageConfig);
41
84
  const currentPage = options.Page;
@@ -43,7 +86,7 @@ export async function handlePageHmr(options, newUrl, generation, readPageData, s
43
86
  if (await applyRouterHmrUpdate(options, newUrl, currentPage, nextPage)) {
44
87
  return;
45
88
  }
46
- applyDirectHmrRender(options, nextPage, getPageDataFromDocument(options), readPageData, setPageState, generation);
89
+ await applyDirectHmrRender(options, nextPage, readPageData, setPageState, generation, isSuperseded);
47
90
  }
48
91
  catch (error) {
49
92
  console.error(`[ecopages] Failed to hot-reload ${options.isMdx ? 'MDX' : 'React'} component:`, error);
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * @remarks
5
5
  * The entry module supplies the page tree and module resolution details. This
6
- * module owns document state, navigation ownership, cleanup, and HMR so those
7
- * behaviors stay identical for readable and compiled bootstraps.
6
+ * module owns document state, navigation ownership, cleanup, and HMR. It ships
7
+ * as `@ecopages/react/page-hydration`, which the generated Page entry imports by
8
+ * package name like React itself.
8
9
  */
9
10
  export type PageRoot = {
10
11
  render: (tree: unknown) => void;
@@ -25,14 +26,14 @@ export type PageData = {
25
26
  props: Record<string, unknown>;
26
27
  };
27
28
  export { resolvePageComponent } from './page-hydration-module.js';
29
+ export { readPageDataDocument } from '../page-data-reader.js';
28
30
  /** Configuration passed from a generated Page hydration entry. */
29
31
  export type PageHydrationOptions = {
30
32
  scriptId: string;
31
33
  pageModuleUrl: string;
32
34
  Page: unknown;
33
35
  pageDataReader: {
34
- readPageDataDocument: () => PageData;
35
- getPageDataFromDocument: () => Record<string, unknown>;
36
+ readPageDataDocument: (source?: Pick<Document, 'getElementById'>) => PageData;
36
37
  };
37
38
  runtime: PageReactRuntime;
38
39
  createTree: (Page: unknown, props: Record<string, unknown>) => unknown;
@@ -41,7 +42,7 @@ export type PageHydrationOptions = {
41
42
  normalizePageConfig?: (config: unknown) => void;
42
43
  hmr?: {
43
44
  importPath: string;
44
- getLayoutStack?: (Page: unknown) => string;
45
+ getLayouts?: (Page: unknown) => readonly unknown[];
45
46
  };
46
47
  };
47
48
  /**
@@ -3,10 +3,12 @@
3
3
  *
4
4
  * @remarks
5
5
  * The entry module supplies the page tree and module resolution details. This
6
- * module owns document state, navigation ownership, cleanup, and HMR so those
7
- * behaviors stay identical for readable and compiled bootstraps.
6
+ * module owns document state, navigation ownership, cleanup, and HMR. It ships
7
+ * as `@ecopages/react/page-hydration`, which the generated Page entry imports by
8
+ * package name like React itself.
8
9
  */
9
10
  export { resolvePageComponent } from './page-hydration-module.js';
11
+ export { readPageDataDocument } from '../page-data-reader.js';
10
12
  import { handlePageHmr } from './page-hydration-hmr.js';
11
13
  /** Returns and lazily initializes the shared page runtime on `window`. */
12
14
  function getRuntime() {
@@ -22,9 +24,9 @@ function recordHydrationTiming() {
22
24
  return;
23
25
  pageWindow.__ECO_DEV_HYDRATION_MS__ = Math.round(performance.now() - pageWindow.__ECO_DEV_HYDRATION_STARTED__);
24
26
  }
25
- /** Reads the current page-data document through the shared reader contract. */
26
- function readPageData(options) {
27
- return options.pageDataReader.readPageDataDocument();
27
+ /** Reads the page data of `source`, the live document by default, through the shared reader contract. */
28
+ function readPageData(options, source) {
29
+ return options.pageDataReader.readPageDataDocument(source);
28
30
  }
29
31
  /** Publishes the current module URL and props for router/navigation consumers. */
30
32
  function setPageState(options, pageData) {
@@ -93,7 +95,7 @@ function registerHmr(options) {
93
95
  const runtime = getRuntime();
94
96
  const generation = runtime.react?.mountGeneration ?? 0;
95
97
  runtime.hmrHandlers ??= {};
96
- runtime.hmrHandlers[options.hmr.importPath] = (newUrl) => handlePageHmr(options, newUrl, generation, readPageData, setPageState, (opts) => opts.pageDataReader.getPageDataFromDocument());
98
+ runtime.hmrHandlers[options.hmr.importPath] = (newUrl) => handlePageHmr(options, newUrl, generation, readPageData, setPageState);
97
99
  }
98
100
  /**
99
101
  * Returns the target's children that were not there before `hydrateRoot`.
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The element React renders in place of a Foreign Subtree, shared by the server render and the browser.
3
+ *
4
+ * @remarks
5
+ * The server wraps each Foreign Subtree's HTML in this element; in the browser, a Component another Integration
6
+ * owns renders the same element with that HTML as `dangerouslySetInnerHTML`, so hydration keeps the server DOM
7
+ * instead of calling the Component's `render`. The module has no server or React imports, since the browser
8
+ * bootstraps import it.
9
+ *
10
+ * @module
11
+ */
12
+ import type { EcoComponent } from '@ecopages/core';
13
+ export declare const FOREIGN_SUBTREE_TAG = "eco-foreign-subtree";
14
+ export declare const FOREIGN_SUBTREE_KEY_ATTRIBUTE = "data-eco-foreign-key";
15
+ export declare const FOREIGN_SUBTREE_DISPLAY = "contents";
16
+ /**
17
+ * Names a Foreign Subtree by its Component's identity and its serializable props.
18
+ *
19
+ * @remarks
20
+ * A browser render that does not hydrate, such as a client navigation, finds the server HTML of a Foreign Subtree
21
+ * by this key, so the server and the browser must compute the same one. Two Foreign Subtrees that differ only in
22
+ * props the key leaves out, such as React `children`, share a key, and the browser then takes the first one's HTML
23
+ * for both.
24
+ */
25
+ export declare function getForeignSubtreeKey(component: EcoComponent, props: Record<string, unknown>): string;
26
+ /** Wraps the server HTML of one Foreign Subtree in the element the browser keeps as is. */
27
+ export declare function renderForeignSubtreeBoundary(key: string, html: string): string;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The element React renders in place of a Foreign Subtree, shared by the server render and the browser.
3
+ *
4
+ * @remarks
5
+ * The server wraps each Foreign Subtree's HTML in this element; in the browser, a Component another Integration
6
+ * owns renders the same element with that HTML as `dangerouslySetInnerHTML`, so hydration keeps the server DOM
7
+ * instead of calling the Component's `render`. The module has no server or React imports, since the browser
8
+ * bootstraps import it.
9
+ *
10
+ * @module
11
+ */
12
+ export const FOREIGN_SUBTREE_TAG = 'eco-foreign-subtree';
13
+ export const FOREIGN_SUBTREE_KEY_ATTRIBUTE = 'data-eco-foreign-key';
14
+ export const FOREIGN_SUBTREE_DISPLAY = 'contents';
15
+ function isPlainObject(value) {
16
+ const prototype = Object.getPrototypeOf(value);
17
+ return (prototype === Object.prototype || prototype === null) && !('$$typeof' in value);
18
+ }
19
+ /**
20
+ * Serializes the parts of `value` that both the server and the browser see the same way.
21
+ *
22
+ * @remarks
23
+ * Functions, symbols, React elements and class instances are left out, as `JSON.stringify` leaves out functions:
24
+ * their identity or minified name differs between the two builds. Object keys are sorted.
25
+ */
26
+ function serializeStable(value) {
27
+ if (value === null || typeof value === 'string' || typeof value === 'boolean')
28
+ return JSON.stringify(value);
29
+ if (typeof value === 'number')
30
+ return Number.isFinite(value) ? String(value) : 'null';
31
+ if (typeof value !== 'object')
32
+ return undefined;
33
+ if (Array.isArray(value))
34
+ return `[${value.map((item) => serializeStable(item) ?? 'null').join(',')}]`;
35
+ if (!isPlainObject(value))
36
+ return undefined;
37
+ const entries = Object.keys(value)
38
+ .sort()
39
+ .flatMap((key) => {
40
+ const serialized = serializeStable(value[key]);
41
+ return serialized === undefined ? [] : [`${JSON.stringify(key)}:${serialized}`];
42
+ });
43
+ return `{${entries.join(',')}}`;
44
+ }
45
+ /** 32-bit FNV-1a of `text`, in base 36. */
46
+ function hashText(text) {
47
+ let hash = 0x811c9dc5;
48
+ for (let index = 0; index < text.length; index += 1) {
49
+ hash ^= text.charCodeAt(index);
50
+ hash = Math.imul(hash, 0x01000193);
51
+ }
52
+ return (hash >>> 0).toString(36);
53
+ }
54
+ /**
55
+ * Names a Foreign Subtree by its Component's identity and its serializable props.
56
+ *
57
+ * @remarks
58
+ * A browser render that does not hydrate, such as a client navigation, finds the server HTML of a Foreign Subtree
59
+ * by this key, so the server and the browser must compute the same one. Two Foreign Subtrees that differ only in
60
+ * props the key leaves out, such as React `children`, share a key, and the browser then takes the first one's HTML
61
+ * for both.
62
+ */
63
+ export function getForeignSubtreeKey(component, props) {
64
+ return hashText(`${component.config?.identity?.id ?? ''}\u0000${serializeStable(props) ?? ''}`);
65
+ }
66
+ /** Wraps the server HTML of one Foreign Subtree in the element the browser keeps as is. */
67
+ export function renderForeignSubtreeBoundary(key, html) {
68
+ return `<${FOREIGN_SUBTREE_TAG} ${FOREIGN_SUBTREE_KEY_ATTRIBUTE}="${key}" style="display:${FOREIGN_SUBTREE_DISPLAY}">${html}</${FOREIGN_SUBTREE_TAG}>`;
69
+ }
@@ -17,6 +17,8 @@ import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
17
17
  * Configuration for the HydrationAssetService.
18
18
  */
19
19
  export interface HydrationAssetServiceConfig {
20
+ /** The app root: entry names and keys hash source paths relative to it, so they survive a moved project. */
21
+ rootDir: string;
20
22
  srcDir: string;
21
23
  routerAdapter?: ReactRouterAdapter;
22
24
  assetProcessingService: AssetProcessingService;
@@ -31,7 +33,6 @@ type PageDependencyOptions = {
31
33
  pageModuleUrlExpression: string;
32
34
  bundleOptions: Record<string, unknown>;
33
35
  hmrEnabled: boolean;
34
- useBrowserRuntimeImports: boolean;
35
36
  isMdx: boolean;
36
37
  };
37
38
  /**
@@ -42,23 +43,26 @@ type PageDependencyOptions = {
42
43
  * separate component ID, so repeated uses share browser assets without sharing
43
44
  * a React root.
44
45
  *
45
- * @param componentFile - Absolute source path of the React component.
46
+ * @param sourceKey - Source path of the React component relative to the app root (`toRootRelativePath`).
46
47
  * @param config - Optional component identity used to distinguish entries.
47
48
  * @returns Stable key used in selectors and asset names.
48
49
  */
49
- export declare function getIslandComponentKey(componentFile: string, config?: EcoComponentConfig): string;
50
+ export declare function getIslandComponentKey(sourceKey: string, config?: EcoComponentConfig): string;
51
+ type IslandInput = {
52
+ file: string;
53
+ config?: EcoComponentConfig;
54
+ };
50
55
  /**
51
56
  * Manages the creation of client-side hydration assets for React pages and component islands.
52
57
  */
53
58
  export declare class HydrationAssetService {
54
59
  private readonly config;
55
- private readonly islandScriptCompiler;
56
- private readonly pageScriptCompiler;
57
- private static readonly ROUTER_PAGE_GROUPED_BUNDLE_ID;
58
60
  constructor(config: HydrationAssetServiceConfig);
61
+ private toSourceKey;
59
62
  private getIslandBundleName;
63
+ private getIslandComponentKey;
60
64
  private getIslandHydrationName;
61
- private getRouterPageGroupedEntryName;
65
+ private getPageGroupedEntryName;
62
66
  /**
63
67
  * Resolves the browser import path used for a React-owned page or island module.
64
68
  *
@@ -72,9 +76,10 @@ export declare class HydrationAssetService {
72
76
  * Creates the page-owned route entry asset for hydration and client navigation.
73
77
  *
74
78
  * @remarks
75
- * The entry is compiled asynchronously from the editable browser lifecycle.
76
- * Production router pages may be grouped into the Page Browser Graph, while
77
- * HMR entries remain separate ESM scripts with browser-resolvable imports.
79
+ * The entry imports the `@ecopages/react/page-hydration` lifecycle and React by package name. Outside HMR it is
80
+ * an entry of the app-wide browser build, so React and every other shared module are chunks it shares with the
81
+ * islands and the other Pages. With HMR it stays a separate unbundled ESM script whose imports core rewrites to
82
+ * dev-transform and vendor URLs.
78
83
  */
79
84
  createPageDependencies(options: PageDependencyOptions): Promise<AssetDefinition[]>;
80
85
  /**
@@ -85,35 +90,38 @@ export declare class HydrationAssetService {
85
90
  * HMR keeps per-file transform URLs and does not start a disk bundle.
86
91
  */
87
92
  buildPageClientAssets(input: {
88
- islands: Array<{
89
- file: string;
90
- config?: EcoComponentConfig;
91
- }>;
93
+ islands: IslandInput[];
92
94
  lazyEntries?: AssetDefinition[];
93
95
  }): Promise<ProcessedAsset[]>;
94
- /** Collects React island hydration entries for the production app browser build. */
95
- collectAppBrowserClientBuildEntries(islands: Array<{
96
- file: string;
97
- config?: EcoComponentConfig;
98
- }>): Promise<PageClientBuildEntry[]>;
99
- /** Keeps one entry per component; a file that declares several island components keeps each of them. */
96
+ /** Collects React island hydration entries for a grouped browser build, which is the app-wide build in production. */
97
+ collectAppBrowserClientBuildEntries(islands: IslandInput[]): Promise<PageClientBuildEntry[]>;
98
+ /**
99
+ * Keeps one entry per component; a file that declares several island components keeps each of them.
100
+ *
101
+ * @remarks
102
+ * An island's `file` is its identity file, relative to the app root; it is resolved here so every later step
103
+ * bundles and watches the real file.
104
+ */
100
105
  private uniqueIslands;
101
106
  private buildHmrPageClientAssets;
107
+ /**
108
+ * Builds the island hydration entries and lazy entries in one grouped browser build.
109
+ *
110
+ * @remarks
111
+ * Each hydration entry imports its island module and React by package name, so the build shares React, the
112
+ * bootstrap and every common module between them as chunks.
113
+ */
102
114
  private buildGroupedPageClientAssets;
103
- private createGroupedIslandEntries;
104
- private indexSrcUrlsByEntryName;
105
- private createGroupedHydrationScripts;
106
115
  private buildHmrIslandAssets;
116
+ /**
117
+ * @remarks
118
+ * The entry lists the island file it imports by absolute path in `bundledSourceFilepaths`, so its dependency key
119
+ * hashes its text with that file written relative to the app root; its name hashes the root-relative path too.
120
+ */
107
121
  private createIslandHydrationScript;
108
122
  /**
109
123
  * Creates the page browser graph dependency declarations for a React page.
110
124
  *
111
- * @remarks
112
- * Chooses shared vendor import URLs when HMR is on, when running a non-production
113
- * hosted runtime with HMR off, or when a router adapter is configured (router
114
- * pages always externalize to shared runtimes). Production non-router pages
115
- * may inline React into the page bundle instead.
116
- *
117
125
  * @param pagePath - Absolute file path of the page
118
126
  * @param isMdx - Whether the page is an MDX file
119
127
  * @param declaredModules - Explicitly declared browser module specifiers