@ecopages/react 0.9.0 → 0.10.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 (41) hide show
  1. package/README.md +12 -22
  2. package/package.json +4 -4
  3. package/src/bundling/bundle.js +16 -9
  4. package/src/client-graph/ast-transform-eco-page.d.ts +14 -1
  5. package/src/client-graph/ast-transform-eco-page.js +60 -13
  6. package/src/client-graph/ast-transform-stripped-imports.js +1 -1
  7. package/src/client-graph/ast-transform-walk-imports.js +1 -1
  8. package/src/client-graph/boundary-plugin.d.ts +19 -0
  9. package/src/client-graph/boundary-plugin.js +51 -12
  10. package/src/client-graph/foreign-boundary-rewrite.d.ts +18 -3
  11. package/src/client-graph/foreign-boundary-rewrite.js +196 -45
  12. package/src/client-graph/foreign-jsx-reach.d.ts +21 -2
  13. package/src/client-graph/foreign-jsx-reach.js +25 -9
  14. package/src/client-graph/foreign-module.d.ts +45 -0
  15. package/src/client-graph/foreign-module.js +132 -0
  16. package/src/client-graph/reachability-client-roots.js +28 -0
  17. package/src/hmr/hmr-strategy.d.ts +3 -0
  18. package/src/hmr/hmr-strategy.js +7 -0
  19. package/src/hydration/browser/foreign-boundary.d.ts +12 -0
  20. package/src/hydration/browser/foreign-boundary.js +19 -0
  21. package/src/hydration/browser/page-hydration-hmr.d.ts +1 -0
  22. package/src/hydration/browser/page-hydration-hmr.js +1 -1
  23. package/src/hydration/browser/page-hydration.d.ts +2 -1
  24. package/src/hydration/browser/page-hydration.js +3 -2
  25. package/src/hydration/hydration-page-entry-source.js +3 -3
  26. package/src/hydration/page-data-manifest.d.ts +22 -1
  27. package/src/hydration/page-data-manifest.js +38 -3
  28. package/src/hydration/page-data-reader.d.ts +2 -1
  29. package/src/hydration/page-data-reader.js +4 -2
  30. package/src/hydration/page-payload.d.ts +6 -15
  31. package/src/hydration/page-payload.js +5 -42
  32. package/src/hydration/serialize-page-data-script.d.ts +4 -4
  33. package/src/hydration/serialize-page-data-script.js +6 -6
  34. package/src/plugin/react.plugin.js +2 -0
  35. package/src/render/component-ownership.d.ts +1 -6
  36. package/src/render/component-ownership.js +0 -3
  37. package/src/render/component-ssr.d.ts +0 -1
  38. package/src/render/component-ssr.js +0 -7
  39. package/src/render/layout-compose.d.ts +16 -8
  40. package/src/render/layout-compose.js +13 -36
  41. package/src/render/react-renderer.js +24 -37
@@ -1,3 +1,28 @@
1
+ import { getInlineLayoutEntries, getLayoutTiers, isPropertyNamed } from './ast-transform-eco-page.js';
2
+ /**
3
+ * Adds the layout tiers of a `layout` option as roots: every tier except the `props` factory of an inline entry.
4
+ *
5
+ * @remarks
6
+ * The browser renders the layout components, so what they reference is browser code. An inline entry's factory
7
+ * runs only on the server and the page transform removes it. A tier that is not an object literal, such as an
8
+ * entry imported from another module, is a root whole, so its module's export is requested and its server
9
+ * imports fail the browser build instead of turning the tier into `undefined`.
10
+ */
11
+ function collectLayoutRoots(layout, roots) {
12
+ const inlineEntries = new Set(getInlineLayoutEntries(layout));
13
+ for (const tier of getLayoutTiers(layout)) {
14
+ if (!tier)
15
+ continue;
16
+ if (!inlineEntries.has(tier)) {
17
+ roots.push(tier);
18
+ continue;
19
+ }
20
+ for (const property of tier.properties) {
21
+ if (!isPropertyNamed(property, 'props'))
22
+ roots.push(property.type === 'Property' ? property.value : property);
23
+ }
24
+ }
25
+ }
1
26
  function collectEcoPageClientProperties(arg, roots) {
2
27
  if (!arg || arg.type !== 'ObjectExpression')
3
28
  return;
@@ -6,6 +31,9 @@ function collectEcoPageClientProperties(arg, roots) {
6
31
  if (['render', 'errorBoundary', 'loadingFallback', 'clientScripts'].includes(prop.key.name)) {
7
32
  roots.push(prop.value);
8
33
  }
34
+ else if (isPropertyNamed(prop, 'layout')) {
35
+ collectLayoutRoots(prop.value, roots);
36
+ }
9
37
  }
10
38
  }
11
39
  }
@@ -19,6 +19,8 @@ export interface ReactHmrStrategyOptions {
19
19
  getMdxLoaderPlugin?: () => EcoBuildPlugin;
20
20
  ownedTemplateExtensions?: string[];
21
21
  allTemplateExtensions?: string[];
22
+ /** The Integration that owns a file, so React names a foreign Eco Component by its identity. */
23
+ integrationOf: (filePath: string) => string | undefined;
22
24
  }
23
25
  /**
24
26
  * Strategy for handling React component HMR updates.
@@ -32,6 +34,7 @@ export declare class ReactHmrStrategy extends HmrStrategy {
32
34
  private readonly context;
33
35
  private readonly pageMetadataCache;
34
36
  private readonly routerAdapter?;
37
+ private readonly foreignModuleOf;
35
38
  private importNodePageModule;
36
39
  private getDevTransformPluginOptions;
37
40
  constructor(options: ReactHmrStrategyOptions);
@@ -14,6 +14,7 @@ import { isPathInside } from '@ecopages/core/build';
14
14
  import { Logger } from '@ecopages/logger';
15
15
  import { createClientGraphBoundaryPlugin, createForeignBoundaryPlugin } from '../client-graph/boundary-plugin.js';
16
16
  import { REACT_BOUNDARY_VARIANT } from '../client-graph/foreign-boundary-rewrite.js';
17
+ import { createForeignModuleReader } from '../client-graph/foreign-module.js';
17
18
  import { getReactClientGraphAllowSpecifiers } from '../bundling/bundle.js';
18
19
  import { getReactBrowserPackages } from '../bundling/bootstrap-package-paths.js';
19
20
  import { buildReactDevTransformPlugins, resolveReactDeclaredModulesForEntrypoint, } from './react-hmr-dev-transform-plugins.js';
@@ -31,6 +32,7 @@ export class ReactHmrStrategy extends HmrStrategy {
31
32
  context;
32
33
  pageMetadataCache;
33
34
  routerAdapter;
35
+ foreignModuleOf;
34
36
  async importNodePageModule(entrypointPath) {
35
37
  return await this.context.importServerModule(entrypointPath);
36
38
  }
@@ -51,6 +53,10 @@ export class ReactHmrStrategy extends HmrStrategy {
51
53
  this.getMdxLoaderPlugin = options.getMdxLoaderPlugin;
52
54
  this.ownedTemplateExtensions = new Set(options.ownedTemplateExtensions ?? ['.tsx']);
53
55
  this.allTemplateExtensions = [...(options.allTemplateExtensions ?? ['.tsx'])].sort((a, b) => b.length - a.length);
56
+ this.foreignModuleOf = createForeignModuleReader({
57
+ rootDir: this.projectRoot,
58
+ integrationOf: options.integrationOf,
59
+ });
54
60
  }
55
61
  getBuildPlugins(declaredModules) {
56
62
  return [
@@ -67,6 +73,7 @@ export class ReactHmrStrategy extends HmrStrategy {
67
73
  return templateExtension !== undefined && !this.ownedTemplateExtensions.has(templateExtension);
68
74
  },
69
75
  isSharedFile: (filePath) => !this.isReactEntrypoint(filePath),
76
+ foreignModuleOf: this.foreignModuleOf,
70
77
  }),
71
78
  ];
72
79
  }
@@ -9,6 +9,8 @@
9
9
  *
10
10
  * @module
11
11
  */
12
+ import { type ComponentType } from 'react';
13
+ import { type ComponentIdentity } from '@ecopages/core';
12
14
  /**
13
15
  * Returns the component type React renders for `value`: a boundary when it is an Eco Component another
14
16
  * Integration owns, `value` itself otherwise.
@@ -23,6 +25,16 @@
23
25
  * One boundary type per Component keeps React from re-mounting it on a parent render.
24
26
  */
25
27
  export declare function foreignBoundary<T>(value: T): T;
28
+ /**
29
+ * Returns the boundary of the Eco Component another Integration owns that `identity` names, without its module.
30
+ *
31
+ * @remarks
32
+ * The stub module React's client graph loads for a foreign file exports one of these per static Component, so the
33
+ * Component's module and its imports stay out of React's bundle; the boundary only needs the identity to find the
34
+ * server HTML. One boundary type per identity keeps React from re-mounting it on a parent render, even when a
35
+ * development transform inlines the same stub into several modules.
36
+ */
37
+ export declare function foreignBoundaryReference(identity: ComponentIdentity): ComponentType<Record<string, unknown>>;
26
38
  /**
27
39
  * Wraps a namespace import of a module another Integration owns, so `ns.Component` is its boundary.
28
40
  */
@@ -118,6 +118,25 @@ export function foreignBoundary(value) {
118
118
  }
119
119
  return boundary;
120
120
  }
121
+ const references = new Map();
122
+ /**
123
+ * Returns the boundary of the Eco Component another Integration owns that `identity` names, without its module.
124
+ *
125
+ * @remarks
126
+ * The stub module React's client graph loads for a foreign file exports one of these per static Component, so the
127
+ * Component's module and its imports stay out of React's bundle; the boundary only needs the identity to find the
128
+ * server HTML. One boundary type per identity keeps React from re-mounting it on a parent render, even when a
129
+ * development transform inlines the same stub into several modules.
130
+ */
131
+ export function foreignBoundaryReference(identity) {
132
+ let boundary = references.get(identity.id);
133
+ if (!boundary) {
134
+ const component = Object.assign(() => null, { config: { identity } });
135
+ boundary = foreignBoundary(component);
136
+ references.set(identity.id, boundary);
137
+ }
138
+ return boundary;
139
+ }
121
140
  /**
122
141
  * Wraps a namespace import of a module another Integration owns, so `ns.Component` is its boundary.
123
142
  */
@@ -2,6 +2,7 @@ import type { PageHydrationOptions } from './page-hydration.js';
2
2
  type PageData = {
3
3
  moduleUrl?: string;
4
4
  props: Record<string, unknown>;
5
+ tiers?: readonly Record<string, unknown>[];
5
6
  };
6
7
  type PageDataReader = (options: PageHydrationOptions, source?: Pick<Document, 'getElementById'>) => PageData;
7
8
  type PageStateSetter = (options: PageHydrationOptions, pageData: PageData) => void;
@@ -65,7 +65,7 @@ async function applyDirectHmrRender(options, nextPage, readPageData, setPageStat
65
65
  const runtime = getRuntime();
66
66
  if (runtime.page)
67
67
  runtime.page.document = fetchedDocument;
68
- activeRoot.render(options.createTree(nextPage, pageData.props));
68
+ activeRoot.render(options.createTree(nextPage, pageData.props, pageData.tiers));
69
69
  console.log(`[ecopages] ${options.isMdx ? 'MDX' : 'React'} component updated`);
70
70
  }
71
71
  /**
@@ -24,6 +24,7 @@ export type PageReactRuntime = {
24
24
  export type PageData = {
25
25
  moduleUrl?: string;
26
26
  props: Record<string, unknown>;
27
+ tiers?: readonly Record<string, unknown>[];
27
28
  };
28
29
  export { resolvePageComponent } from './page-hydration-module.js';
29
30
  export { readPageDataDocument } from '../page-data-reader.js';
@@ -36,7 +37,7 @@ export type PageHydrationOptions = {
36
37
  readPageDataDocument: (source?: Pick<Document, 'getElementById'>) => PageData;
37
38
  };
38
39
  runtime: PageReactRuntime;
39
- createTree: (Page: unknown, props: Record<string, unknown>) => unknown;
40
+ createTree: (Page: unknown, props: Record<string, unknown>, tiers?: readonly Record<string, unknown>[]) => unknown;
40
41
  hasRouter: boolean;
41
42
  isMdx: boolean;
42
43
  normalizePageConfig?: (config: unknown) => void;
@@ -34,6 +34,7 @@ function setPageState(options, pageData) {
34
34
  runtime.page = {
35
35
  module: pageData.moduleUrl || options.pageModuleUrl,
36
36
  props: pageData.props,
37
+ ...(pageData.tiers && { tiers: pageData.tiers }),
37
38
  };
38
39
  }
39
40
  /**
@@ -176,7 +177,7 @@ function mount(options) {
176
177
  setPageState(options, pageData);
177
178
  if (runtime.react?.pageRoot) {
178
179
  if (!options.hasRouter) {
179
- runtime.react.pageRoot.render(options.createTree(options.Page, pageData.props));
180
+ runtime.react.pageRoot.render(options.createTree(options.Page, pageData.props, pageData.tiers));
180
181
  }
181
182
  return;
182
183
  }
@@ -196,7 +197,7 @@ function mount(options) {
196
197
  requireReloadForHmr(options);
197
198
  restoreChildNodes(target, serverNodes, serverClones, addedNodes);
198
199
  };
199
- root = options.runtime.hydrateRoot(target, options.createTree(options.Page, pageData.props), {
200
+ root = options.runtime.hydrateRoot(target, options.createTree(options.Page, pageData.props, pageData.tiers), {
200
201
  onRecoverableError: (error) => console.warn('[ecopages] Hydration error:', error),
201
202
  onUncaughtError: (error, errorInfo) => {
202
203
  reportError(error);
@@ -26,11 +26,11 @@ function buildRouterImports(options) {
26
26
  }
27
27
  function buildRouterTree(options) {
28
28
  if (!options.routerComponents) {
29
- return 'const createTree = (Page, props) => composeLayoutPageTree(Page, props);';
29
+ return 'const createTree = (Page, props, tiers) => composeLayoutPageTree(Page, props, tiers ? { tierProps: tiers } : undefined);';
30
30
  }
31
- return `const createTree = (Page, props) => {
31
+ return `const createTree = (Page, props, tiers) => {
32
32
  const pageContent = createElement(${options.routerComponents.pageContent});
33
- return createElement(${options.routerComponents.router}, ${options.routerPropsExpression}, pageContent);
33
+ return createElement(${options.routerComponents.router}, { ...(${options.routerPropsExpression}), tierProps: tiers }, pageContent);
34
34
  };`;
35
35
  }
36
36
  function buildNormalizationImport(options) {
@@ -16,14 +16,25 @@
16
16
  * empty props and no module URL from the manifest
17
17
  * - HMR: `moduleUrlOverride` still bypasses document discovery
18
18
  * - legacy flat props may include a string `schemaVersion` field without being treated as an envelope
19
+ * - `tiers` (the props each layout tier renders with, outer to inner) is optional on the same schema version:
20
+ * new client / old document finds none and runs layout factories as before; old client / new document ignores
21
+ * it; a legacy flat payload carries it under {@link ECO_PAGE_DATA_TIERS_KEY}, which never reaches page props;
22
+ * an invalid `tiers` is ignored without rejecting the envelope
23
+ * - `props` carries what the Page's `props` hook returned plus its Params and Query, never request `locals`; an old
24
+ * document that still serialized `props.locals` hands it to the Page as an ordinary prop, so the schema version
25
+ * is unchanged
19
26
  */
20
27
  export declare const ECO_PAGE_DATA_SCHEMA_VERSION: 1;
28
+ /** Reserved key carrying `tiers` inside a legacy flat payload. */
29
+ export declare const ECO_PAGE_DATA_TIERS_KEY = "__ecoTiers";
21
30
  export type EcoPageDataProps = Record<string, unknown>;
22
31
  export type EcoPageDataManifestV1 = {
23
32
  schemaVersion: typeof ECO_PAGE_DATA_SCHEMA_VERSION;
24
33
  navigationOwner: 'react-router';
25
34
  moduleUrl: string;
26
35
  props: EcoPageDataProps;
36
+ /** The props each layout tier renders with, outer to inner, resolved on the server. */
37
+ tiers?: readonly EcoPageDataProps[];
27
38
  };
28
39
  export type EcoPageDataDocumentPayload = EcoPageDataManifestV1 | EcoPageDataProps;
29
40
  /**
@@ -34,6 +45,14 @@ export declare function isEcoPageDataManifestV1(value: unknown): value is EcoPag
34
45
  * Extracts browser page props from either a v1 envelope or a legacy flat payload.
35
46
  */
36
47
  export declare function resolveEcoPageDataProps(payload: unknown): EcoPageDataProps;
48
+ /**
49
+ * Extracts the server-resolved layout tier props from a v1 envelope or a legacy flat payload.
50
+ *
51
+ * @remarks
52
+ * Returns `undefined` unless the value is an array of plain objects, so a malformed value falls back to layout
53
+ * factories instead of rendering a layout with garbage props.
54
+ */
55
+ export declare function resolveEcoPageDataTiers(payload: unknown): readonly EcoPageDataProps[] | undefined;
37
56
  /**
38
57
  * Extracts the page module URL from a v1 envelope when present.
39
58
  */
@@ -44,6 +63,7 @@ export declare function resolveEcoPageDataModuleUrl(payload: unknown): string |
44
63
  export declare function createEcoPageDataManifestV1(input: {
45
64
  moduleUrl: string;
46
65
  props: EcoPageDataProps;
66
+ tiers?: readonly EcoPageDataProps[];
47
67
  }): EcoPageDataManifestV1;
48
68
  /**
49
69
  * Normalizes flat page props or an existing envelope into the document payload shape.
@@ -51,7 +71,8 @@ export declare function createEcoPageDataManifestV1(input: {
51
71
  * @remarks
52
72
  * Shared by server serializers and `EcoPropsScript` so envelope rules stay in one place.
53
73
  * A valid v1 envelope is returned as-is; `options.moduleUrl` is ignored in that case.
54
- * Flat props wrap into a v1 envelope only when `options.moduleUrl` is provided.
74
+ * Flat props wrap into a v1 envelope only when `options.moduleUrl` is provided; the reserved
75
+ * {@link ECO_PAGE_DATA_TIERS_KEY} is then lifted into the envelope's `tiers`, and otherwise stays in the flat object.
55
76
  */
56
77
  export declare function resolvePageDataDocumentPayload(data: EcoPageDataDocumentPayload, options?: {
57
78
  moduleUrl?: string;
@@ -16,8 +16,17 @@
16
16
  * empty props and no module URL from the manifest
17
17
  * - HMR: `moduleUrlOverride` still bypasses document discovery
18
18
  * - legacy flat props may include a string `schemaVersion` field without being treated as an envelope
19
+ * - `tiers` (the props each layout tier renders with, outer to inner) is optional on the same schema version:
20
+ * new client / old document finds none and runs layout factories as before; old client / new document ignores
21
+ * it; a legacy flat payload carries it under {@link ECO_PAGE_DATA_TIERS_KEY}, which never reaches page props;
22
+ * an invalid `tiers` is ignored without rejecting the envelope
23
+ * - `props` carries what the Page's `props` hook returned plus its Params and Query, never request `locals`; an old
24
+ * document that still serialized `props.locals` hands it to the Page as an ordinary prop, so the schema version
25
+ * is unchanged
19
26
  */
20
27
  export const ECO_PAGE_DATA_SCHEMA_VERSION = 1;
28
+ /** Reserved key carrying `tiers` inside a legacy flat payload. */
29
+ export const ECO_PAGE_DATA_TIERS_KEY = '__ecoTiers';
21
30
  /**
22
31
  * Returns whether a parsed JSON value is a versioned page-data envelope.
23
32
  */
@@ -55,10 +64,33 @@ export function resolveEcoPageDataProps(payload) {
55
64
  if (isMalformedPageDataEnvelope(payload)) {
56
65
  return {};
57
66
  }
58
- return payload;
67
+ const { [ECO_PAGE_DATA_TIERS_KEY]: _tiers, ...props } = payload;
68
+ return props;
59
69
  }
60
70
  return {};
61
71
  }
72
+ function isPlainObject(value) {
73
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
74
+ }
75
+ function toTiers(value) {
76
+ return Array.isArray(value) && value.every(isPlainObject) ? value : undefined;
77
+ }
78
+ /**
79
+ * Extracts the server-resolved layout tier props from a v1 envelope or a legacy flat payload.
80
+ *
81
+ * @remarks
82
+ * Returns `undefined` unless the value is an array of plain objects, so a malformed value falls back to layout
83
+ * factories instead of rendering a layout with garbage props.
84
+ */
85
+ export function resolveEcoPageDataTiers(payload) {
86
+ if (isEcoPageDataManifestV1(payload)) {
87
+ return toTiers(payload.tiers);
88
+ }
89
+ if (isPlainObject(payload) && !isMalformedPageDataEnvelope(payload)) {
90
+ return toTiers(payload[ECO_PAGE_DATA_TIERS_KEY]);
91
+ }
92
+ return undefined;
93
+ }
62
94
  /**
63
95
  * Extracts the page module URL from a v1 envelope when present.
64
96
  */
@@ -74,6 +106,7 @@ export function createEcoPageDataManifestV1(input) {
74
106
  navigationOwner: 'react-router',
75
107
  moduleUrl: input.moduleUrl,
76
108
  props: input.props,
109
+ ...(input.tiers && { tiers: input.tiers }),
77
110
  };
78
111
  }
79
112
  /**
@@ -82,7 +115,8 @@ export function createEcoPageDataManifestV1(input) {
82
115
  * @remarks
83
116
  * Shared by server serializers and `EcoPropsScript` so envelope rules stay in one place.
84
117
  * A valid v1 envelope is returned as-is; `options.moduleUrl` is ignored in that case.
85
- * Flat props wrap into a v1 envelope only when `options.moduleUrl` is provided.
118
+ * Flat props wrap into a v1 envelope only when `options.moduleUrl` is provided; the reserved
119
+ * {@link ECO_PAGE_DATA_TIERS_KEY} is then lifted into the envelope's `tiers`, and otherwise stays in the flat object.
86
120
  */
87
121
  export function resolvePageDataDocumentPayload(data, options) {
88
122
  if (isEcoPageDataManifestV1(data)) {
@@ -93,5 +127,6 @@ export function resolvePageDataDocumentPayload(data, options) {
93
127
  if (!moduleUrl) {
94
128
  return props;
95
129
  }
96
- return createEcoPageDataManifestV1({ moduleUrl, props });
130
+ const { [ECO_PAGE_DATA_TIERS_KEY]: rawTiers, ...pageProps } = props;
131
+ return createEcoPageDataManifestV1({ moduleUrl, props: pageProps, tiers: toTiers(rawTiers) });
97
132
  }
@@ -2,13 +2,14 @@ import { type EcoPageDataProps } from './page-data-manifest.js';
2
2
  export type ReadPageDataDocumentResult = {
3
3
  moduleUrl?: string;
4
4
  props: EcoPageDataProps;
5
+ tiers?: readonly EcoPageDataProps[];
5
6
  };
6
7
  /**
7
8
  * Reads `__ECO_PAGE_DATA__` from `source`, supporting both v1 envelopes and legacy flat props.
8
9
  *
9
10
  * @remarks
10
11
  * Always returns unwrapped `props`. `moduleUrl` is set only when the document
11
- * carries a valid v1 envelope. `source` defaults to the live document; a direct HMR update passes the document it
12
+ * carries a valid v1 envelope. `tiers` is set only when the document carries valid server-resolved layout tier props. `source` defaults to the live document; a direct HMR update passes the document it
12
13
  * fetched, whose data is the newer.
13
14
  */
14
15
  export declare function readPageDataDocument(source?: Pick<Document, 'getElementById'>): ReadPageDataDocumentResult;
@@ -1,10 +1,10 @@
1
- import { resolveEcoPageDataModuleUrl, resolveEcoPageDataProps } from './page-data-manifest.js';
1
+ import { resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolveEcoPageDataTiers, } from './page-data-manifest.js';
2
2
  /**
3
3
  * Reads `__ECO_PAGE_DATA__` from `source`, supporting both v1 envelopes and legacy flat props.
4
4
  *
5
5
  * @remarks
6
6
  * Always returns unwrapped `props`. `moduleUrl` is set only when the document
7
- * carries a valid v1 envelope. `source` defaults to the live document; a direct HMR update passes the document it
7
+ * carries a valid v1 envelope. `tiers` is set only when the document carries valid server-resolved layout tier props. `source` defaults to the live document; a direct HMR update passes the document it
8
8
  * fetched, whose data is the newer.
9
9
  */
10
10
  export function readPageDataDocument(source = document) {
@@ -15,9 +15,11 @@ export function readPageDataDocument(source = document) {
15
15
  try {
16
16
  const parsed = JSON.parse(element.textContent);
17
17
  const moduleUrl = resolveEcoPageDataModuleUrl(parsed) ?? undefined;
18
+ const tiers = resolveEcoPageDataTiers(parsed);
18
19
  return {
19
20
  ...(moduleUrl && { moduleUrl }),
20
21
  props: resolveEcoPageDataProps(parsed),
22
+ ...(tiers && { tiers }),
21
23
  };
22
24
  }
23
25
  catch {
@@ -1,4 +1,4 @@
1
- import type { EcoComponentConfig, HtmlTemplateProps, RequestLocals } from '@ecopages/core';
1
+ import type { EcoComponentConfig, HtmlTemplateProps } from '@ecopages/core';
2
2
  import type { IntegrationRendererRenderOptions } from '@ecopages/core/integration';
3
3
  import type { HtmlDocumentContribution } from '@ecopages/core/integration';
4
4
  import type { ReactNode } from 'react';
@@ -6,7 +6,8 @@ type PagePayloadOptions = {
6
6
  pageProps?: HtmlTemplateProps['pageProps'];
7
7
  params: IntegrationRendererRenderOptions<ReactNode>['params'];
8
8
  query: IntegrationRendererRenderOptions<ReactNode>['query'];
9
- safeLocals?: RequestLocals;
9
+ /** The props each layout tier renders with, outer to inner, as the server resolved them. */
10
+ layoutTiers?: readonly Record<string, unknown>[];
10
11
  };
11
12
  type PagePackage = IntegrationRendererRenderOptions<ReactNode>['pagePackage'];
12
13
  /**
@@ -49,20 +50,10 @@ export declare class PagePayloadService {
49
50
  * Builds the browser-safe page-props object embedded into the final HTML.
50
51
  *
51
52
  * @remarks
52
- * Narrower than the full server render input: only routing data, public page
53
- * props, and explicitly allowed locals. Page module identity is threaded via
54
- * `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
53
+ * Carries what the Page's `props` hook returned, its Params and Query, and the layout tier props. Request
54
+ * `locals` never reach it: a Page that needs a value from them returns it from `props`. Page module identity is
55
+ * threaded via `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
55
56
  */
56
57
  buildSerializedPageProps(options: PagePayloadOptions): HtmlTemplateProps['pageProps'];
57
- /**
58
- * Extracts the declared subset of locals for client-side hydration.
59
- *
60
- * @remarks
61
- * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
62
- * request-scoped data. Only keys declared via `Page.requires` are serialized.
63
- * On static pages, `locals` is a Proxy that throws `LocalsAccessError`; this
64
- * method returns `undefined` instead of throwing.
65
- */
66
- getSerializableLocals(locals: RequestLocals | undefined, requiredLocals?: string | readonly string[]): RequestLocals | undefined;
67
58
  }
68
59
  export {};
@@ -1,6 +1,6 @@
1
- import { LocalsAccessError } from '@ecopages/core/errors';
2
1
  import { serializePageDataManifestScript, serializePageDataScript, } from './serialize-page-data-script.js';
3
2
  import { isReactManagedComponent } from '../render/component-ownership.js';
3
+ import { ECO_PAGE_DATA_TIERS_KEY } from './page-data-manifest.js';
4
4
  /**
5
5
  * Builds the serialized page payload React exposes to document shells and the browser.
6
6
  *
@@ -54,53 +54,16 @@ export class PagePayloadService {
54
54
  * Builds the browser-safe page-props object embedded into the final HTML.
55
55
  *
56
56
  * @remarks
57
- * Narrower than the full server render input: only routing data, public page
58
- * props, and explicitly allowed locals. Page module identity is threaded via
59
- * `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
57
+ * Carries what the Page's `props` hook returned, its Params and Query, and the layout tier props. Request
58
+ * `locals` never reach it: a Page that needs a value from them returns it from `props`. Page module identity is
59
+ * threaded via `HtmlTemplateProps.pageModuleUrl`, not serialized page props.
60
60
  */
61
61
  buildSerializedPageProps(options) {
62
62
  return {
63
63
  ...options.pageProps,
64
64
  params: options.params,
65
65
  query: options.query,
66
- ...(options.safeLocals && { locals: options.safeLocals }),
66
+ ...(options.layoutTiers && { [ECO_PAGE_DATA_TIERS_KEY]: options.layoutTiers }),
67
67
  };
68
68
  }
69
- /**
70
- * Extracts the declared subset of locals for client-side hydration.
71
- *
72
- * @remarks
73
- * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
74
- * request-scoped data. Only keys declared via `Page.requires` are serialized.
75
- * On static pages, `locals` is a Proxy that throws `LocalsAccessError`; this
76
- * method returns `undefined` instead of throwing.
77
- */
78
- getSerializableLocals(locals, requiredLocals) {
79
- try {
80
- if (!locals) {
81
- return undefined;
82
- }
83
- const requiredKeys = requiredLocals
84
- ? Array.isArray(requiredLocals)
85
- ? requiredLocals
86
- : [requiredLocals]
87
- : [];
88
- if (requiredKeys.length === 0) {
89
- return undefined;
90
- }
91
- const serializedLocals = Object.fromEntries(requiredKeys
92
- .filter((key) => Object.prototype.hasOwnProperty.call(locals, key))
93
- .map((key) => [key, locals[key]]));
94
- if (Object.keys(serializedLocals).length > 0) {
95
- return serializedLocals;
96
- }
97
- return undefined;
98
- }
99
- catch (error) {
100
- if (error instanceof LocalsAccessError) {
101
- return undefined;
102
- }
103
- throw error;
104
- }
105
- }
106
69
  }
@@ -1,5 +1,5 @@
1
1
  import { type EcoPageDataDocumentPayload, type EcoPageDataProps } from './page-data-manifest.js';
2
- export { ECO_PAGE_DATA_SCHEMA_VERSION, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolvePageDataDocumentPayload, type EcoPageDataDocumentPayload, type EcoPageDataManifestV1, type EcoPageDataProps, } from './page-data-manifest.js';
2
+ export { ECO_PAGE_DATA_SCHEMA_VERSION, ECO_PAGE_DATA_TIERS_KEY, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolveEcoPageDataTiers, resolvePageDataDocumentPayload, type EcoPageDataDocumentPayload, type EcoPageDataManifestV1, type EcoPageDataProps, } from './page-data-manifest.js';
3
3
  /**
4
4
  * Escapes page data JSON for safe embedding in HTML script bodies.
5
5
  */
@@ -17,9 +17,9 @@ export declare function serializePageDataScript(pageProps: EcoPageDataDocumentPa
17
17
  * Emits a versioned page-data envelope for React router documents.
18
18
  *
19
19
  * @remarks
20
- * Canonical HTML serializer for router-enabled pages. SPA commit paths that
21
- * build a React element instead of an HTML string use
22
- * {@link resolvePageDataDocumentPayload} with the same envelope shape.
20
+ * Canonical HTML serializer for router-enabled pages. It builds the envelope through
21
+ * {@link resolvePageDataDocumentPayload}, as `EcoPropsScript` does, so the reserved tiers key in `props` becomes the
22
+ * envelope's `tiers` and never stays in the page props.
23
23
  */
24
24
  export declare function serializePageDataManifestScript(input: {
25
25
  moduleUrl: string;
@@ -1,5 +1,5 @@
1
- import { createEcoPageDataManifestV1, } from './page-data-manifest.js';
2
- export { ECO_PAGE_DATA_SCHEMA_VERSION, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolvePageDataDocumentPayload, } from './page-data-manifest.js';
1
+ import { resolvePageDataDocumentPayload, } from './page-data-manifest.js';
2
+ export { ECO_PAGE_DATA_SCHEMA_VERSION, ECO_PAGE_DATA_TIERS_KEY, createEcoPageDataManifestV1, isEcoPageDataManifestV1, resolveEcoPageDataModuleUrl, resolveEcoPageDataProps, resolveEcoPageDataTiers, resolvePageDataDocumentPayload, } from './page-data-manifest.js';
3
3
  /**
4
4
  * Escapes page data JSON for safe embedding in HTML script bodies.
5
5
  */
@@ -21,10 +21,10 @@ export function serializePageDataScript(pageProps) {
21
21
  * Emits a versioned page-data envelope for React router documents.
22
22
  *
23
23
  * @remarks
24
- * Canonical HTML serializer for router-enabled pages. SPA commit paths that
25
- * build a React element instead of an HTML string use
26
- * {@link resolvePageDataDocumentPayload} with the same envelope shape.
24
+ * Canonical HTML serializer for router-enabled pages. It builds the envelope through
25
+ * {@link resolvePageDataDocumentPayload}, as `EcoPropsScript` does, so the reserved tiers key in `props` becomes the
26
+ * envelope's `tiers` and never stays in the page props.
27
27
  */
28
28
  export function serializePageDataManifestScript(input) {
29
- return serializePageDataScript(createEcoPageDataManifestV1(input));
29
+ return serializePageDataScript(resolvePageDataDocumentPayload(input.props, { moduleUrl: input.moduleUrl }));
30
30
  }
@@ -4,6 +4,7 @@
4
4
  */
5
5
  import { getStylesheetKinds, requireAppRuntime } from '@ecopages/core/integration';
6
6
  import { IntegrationPlugin, } from '@ecopages/core/integration';
7
+ import { findIntegrationForFile } from '@ecopages/core/build';
7
8
  import { Logger } from '@ecopages/logger';
8
9
  import { REACT_PLUGIN_NAME, REACT_SSR_RENDER_TIMEOUT_MAX_MS } from './react.constants.js';
9
10
  import { ReactRenderer } from '../render/react-renderer.js';
@@ -173,6 +174,7 @@ export class ReactPlugin extends IntegrationPlugin {
173
174
  getMdxLoaderPlugin: this.getMdxLoaderPlugin,
174
175
  ownedTemplateExtensions: this.extensions,
175
176
  allTemplateExtensions: context.appConfig.templatesExt,
177
+ integrationOf: (filePath) => findIntegrationForFile(context.appConfig.integrations, filePath)?.name,
176
178
  });
177
179
  manager.registerStrategy(strategy);
178
180
  manager.registerDevTransformContributor(new ReactDevTransformContributor({
@@ -1,15 +1,11 @@
1
1
  /**
2
2
  * Ownership helpers for deciding whether a component stays in the React render lane.
3
3
  */
4
- import type { EcoComponent, EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
4
+ import type { EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
5
5
  import type { FunctionComponent } from 'react';
6
6
  export type SerializableProps = Record<string, unknown>;
7
7
  export type ReactRenderableComponent<P extends SerializableProps = SerializableProps> = FunctionComponent<P> & {
8
8
  config?: EcoComponentConfig;
9
- requires?: string | readonly string[];
10
- };
11
- export type RequiresAwareComponent = {
12
- requires?: string | readonly string[];
13
9
  };
14
10
  /**
15
11
  * Reads the declared integration name for a component or layout.
@@ -32,7 +28,6 @@ export declare function getComponentIntegration(component?: {
32
28
  export declare function isReactManagedComponent(component: {
33
29
  config?: EcoComponentConfig;
34
30
  } | null | undefined, reactIntegrationName: string): boolean;
35
- export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
36
31
  /**
37
32
  * Commits a framework-agnostic component to React semantics.
38
33
  *
@@ -24,9 +24,6 @@ export function isReactManagedComponent(component, reactIntegrationName) {
24
24
  const integration = getComponentIntegration(component);
25
25
  return integration === undefined || integration === reactIntegrationName;
26
26
  }
27
- export function getComponentRequires(component) {
28
- return component?.requires;
29
- }
30
27
  /**
31
28
  * Commits a framework-agnostic component to React semantics.
32
29
  *
@@ -23,7 +23,6 @@ export type ReactForeignSubtreeResolutionContext = {
23
23
  rawChildrenToken?: string;
24
24
  rawChildrenHtml?: string;
25
25
  };
26
- export declare function buildHydrationProps(props: SerializableProps | undefined): SerializableProps;
27
26
  /**
28
27
  * Renders a non-React layout or HTML template and enforces that mixed shells
29
28
  * return serialized HTML.
@@ -3,13 +3,6 @@ import { asReactComponent } from './component-ownership.js';
3
3
  import { ReactRenderError } from './errors.js';
4
4
  import { renderReactHtml } from './react-runtime.js';
5
5
  import { getForeignSubtreeKey, renderForeignSubtreeBoundary } from '../hydration/foreign-subtree.js';
6
- export function buildHydrationProps(props) {
7
- if (!props || !Object.prototype.hasOwnProperty.call(props, 'locals')) {
8
- return props ?? {};
9
- }
10
- const { locals: _locals, ...hydrationProps } = props;
11
- return hydrationProps;
12
- }
13
6
  /**
14
7
  * Renders a non-React layout or HTML template and enforces that mixed shells
15
8
  * return serialized HTML.