@ecopages/react 0.8.0 → 0.10.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 (56) hide show
  1. package/README.md +17 -27
  2. package/package.json +4 -4
  3. package/src/bundling/bundle.d.ts +6 -0
  4. package/src/bundling/bundle.js +23 -9
  5. package/src/client-graph/ast-transform-eco-page.d.ts +14 -1
  6. package/src/client-graph/ast-transform-eco-page.js +60 -13
  7. package/src/client-graph/ast-transform-stripped-imports.js +1 -1
  8. package/src/client-graph/ast-transform-walk-imports.d.ts +0 -1
  9. package/src/client-graph/ast-transform-walk-imports.js +5 -10
  10. package/src/client-graph/ast-transform.d.ts +1 -1
  11. package/src/client-graph/ast-transform.js +1 -2
  12. package/src/client-graph/boundary-plugin-transform.d.ts +0 -1
  13. package/src/client-graph/boundary-plugin-transform.js +1 -2
  14. package/src/client-graph/boundary-plugin.d.ts +19 -0
  15. package/src/client-graph/boundary-plugin.js +54 -16
  16. package/src/client-graph/foreign-boundary-rewrite.d.ts +18 -3
  17. package/src/client-graph/foreign-boundary-rewrite.js +199 -48
  18. package/src/client-graph/foreign-jsx-reach.d.ts +21 -2
  19. package/src/client-graph/foreign-jsx-reach.js +56 -14
  20. package/src/client-graph/foreign-module.d.ts +45 -0
  21. package/src/client-graph/foreign-module.js +132 -0
  22. package/src/client-graph/module-classification.d.ts +0 -1
  23. package/src/client-graph/module-classification.js +0 -4
  24. package/src/client-graph/reachability-analyzer.d.ts +0 -1
  25. package/src/client-graph/reachability-analyzer.js +0 -5
  26. package/src/client-graph/reachability-client-roots.js +28 -0
  27. package/src/client-graph/requested-exports-plan.d.ts +1 -1
  28. package/src/client-graph/requested-exports-plan.js +1 -1
  29. package/src/client-graph/specifier-classification.js +2 -2
  30. package/src/hmr/hmr-strategy.d.ts +5 -2
  31. package/src/hmr/hmr-strategy.js +12 -5
  32. package/src/hydration/browser/foreign-boundary.d.ts +12 -0
  33. package/src/hydration/browser/foreign-boundary.js +19 -0
  34. package/src/hydration/browser/page-hydration-hmr.d.ts +1 -0
  35. package/src/hydration/browser/page-hydration-hmr.js +2 -2
  36. package/src/hydration/browser/page-hydration.d.ts +2 -1
  37. package/src/hydration/browser/page-hydration.js +3 -2
  38. package/src/hydration/hydration-page-entry-source.js +3 -3
  39. package/src/hydration/page-data-manifest.d.ts +22 -1
  40. package/src/hydration/page-data-manifest.js +38 -3
  41. package/src/hydration/page-data-reader.d.ts +2 -1
  42. package/src/hydration/page-data-reader.js +4 -2
  43. package/src/hydration/page-payload.d.ts +6 -15
  44. package/src/hydration/page-payload.js +5 -42
  45. package/src/hydration/serialize-page-data-script.d.ts +4 -4
  46. package/src/hydration/serialize-page-data-script.js +6 -6
  47. package/src/page/page-module.d.ts +4 -2
  48. package/src/page/page-module.js +8 -23
  49. package/src/plugin/react.plugin.js +2 -0
  50. package/src/render/component-ownership.d.ts +1 -6
  51. package/src/render/component-ownership.js +0 -3
  52. package/src/render/component-ssr.d.ts +0 -1
  53. package/src/render/component-ssr.js +0 -7
  54. package/src/render/layout-compose.d.ts +16 -8
  55. package/src/render/layout-compose.js +13 -36
  56. package/src/render/react-renderer.js +37 -55
@@ -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
  }
@@ -12,8 +12,6 @@ import { type EcoComponentConfig, type EcoPageFile } from '@ecopages/core';
12
12
  * Configuration for the PageModuleService.
13
13
  */
14
14
  export interface PageModuleServiceConfig {
15
- layoutsDir?: string;
16
- componentsDir?: string;
17
15
  mdxExtensions: string[];
18
16
  integrationName: string;
19
17
  hasRouterAdapter: boolean;
@@ -30,6 +28,10 @@ export declare class PageModuleService {
30
28
  isMdxFile(filePath: string): boolean;
31
29
  /**
32
30
  * Ensures that an EcoComponentConfig has canonical identity attached.
31
+ *
32
+ * @remarks
33
+ * A config the build stamped keeps its identity. One without it was not declared by a literal `eco.*` call, so
34
+ * it is bound to the page that reached it and its relative paths resolve against that page.
33
35
  */
34
36
  ensureConfigFileMetadata(config: EcoComponentConfig, pagePath: string): EcoComponentConfig;
35
37
  hasModulesInConfig(config: EcoComponentConfig | undefined): boolean;
@@ -7,10 +7,8 @@
7
7
  *
8
8
  * @module
9
9
  */
10
- import { path } from '@ecopages/file-system/path';
11
10
  import { bindComponentIdentity, getComponentIdentity, getComponentOwner, } from '@ecopages/core';
12
11
  import { contentHash } from '@ecopages/core/build';
13
- import { fileSystem } from '@ecopages/file-system';
14
12
  import { someInConfigTree } from '../client-graph/component-config-traversal.js';
15
13
  import { collectPageDeclaredModulesFromModule } from '../client-graph/declared-modules.js';
16
14
  /**
@@ -29,34 +27,21 @@ export class PageModuleService {
29
27
  }
30
28
  /**
31
29
  * Ensures that an EcoComponentConfig has canonical identity attached.
30
+ *
31
+ * @remarks
32
+ * A config the build stamped keeps its identity. One without it was not declared by a literal `eco.*` call, so
33
+ * it is bound to the page that reached it and its relative paths resolve against that page.
32
34
  */
33
35
  ensureConfigFileMetadata(config, pagePath) {
34
36
  const identity = getComponentIdentity(config);
35
37
  if (identity?.file) {
36
38
  return config;
37
39
  }
38
- const buildIdentity = (file) => ({
39
- id: identity?.id ?? BigInt(`0x${contentHash(file, 16)}`).toString(36),
40
+ return bindComponentIdentity({
41
+ id: identity?.id ?? BigInt(`0x${contentHash(pagePath, 16)}`).toString(36),
40
42
  integration: getComponentOwner(config, this.config.integrationName),
41
- file,
42
- });
43
- const resolveDependencyValue = (value) => typeof value === 'string' ? value : value.src;
44
- const dependencyPaths = [
45
- ...(config.dependencies?.stylesheets ?? []).map(resolveDependencyValue),
46
- ...(config.dependencies?.scripts ?? []).map(resolveDependencyValue),
47
- ]
48
- .filter((value) => Boolean(value))
49
- .filter((value) => value.startsWith('./') || value.startsWith('../'));
50
- const candidateDirs = [this.config.layoutsDir, this.config.componentsDir, path.dirname(pagePath)].filter((value) => typeof value === 'string' && value.length > 0);
51
- for (const dependencyPath of dependencyPaths) {
52
- for (const candidateDir of candidateDirs) {
53
- const resolvedDependency = path.resolve(candidateDir, dependencyPath);
54
- if (fileSystem.exists(resolvedDependency)) {
55
- return bindComponentIdentity(buildIdentity(path.join(candidateDir, path.basename(pagePath))), config);
56
- }
57
- }
58
- }
59
- return bindComponentIdentity(buildIdentity(pagePath), config);
43
+ file: pagePath,
44
+ }, config);
60
45
  }
61
46
  hasModulesInConfig(config) {
62
47
  return someInConfigTree(config, (node) => node.dependencies?.modules?.some((entry) => entry.trim().length > 0) ?? false);
@@ -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.
@@ -18,6 +18,14 @@ export type LayoutComposeOptions = {
18
18
  };
19
19
  /** Records which tiers render, so a server render can tell a layout that drops its children. */
20
20
  renderTracker?: LayoutRenderTracker;
21
+ /**
22
+ * The props each layout tier renders with, outer to inner, already resolved on the server.
23
+ *
24
+ * @remarks
25
+ * When given, composition renders tier `i` with `tierProps[i]` and never calls a layout props factory, so the
26
+ * browser needs no request code to reproduce what the server rendered.
27
+ */
28
+ tierProps?: readonly Record<string, unknown>[];
21
29
  };
22
30
  export type LayoutShellEntry = {
23
31
  component: EcoComponent;
@@ -27,18 +35,18 @@ export type ComposablePage<P extends Record<string, unknown> = Record<string, un
27
35
  config?: Pick<EcoComponentConfig, 'layouts' | 'layoutEntries'>;
28
36
  };
29
37
  /**
30
- * Reads request-scoped layout context from serialized page props.
38
+ * Reads the Params and Query of a layout context from serialized page props.
39
+ *
40
+ * @remarks
41
+ * Serialized page props never carry `locals`; a server render passes them in `options.context`.
31
42
  */
32
43
  export declare function resolveLayoutContext(pageProps: Record<string, unknown>): LayoutComposeContext;
33
44
  /**
34
- * Builds layout prop factory context from document-shell layout entries.
45
+ * Resolves props for one layout entry: what its `props` factory returns, or nothing.
35
46
  *
36
47
  * @remarks
37
- * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
38
- */
39
- export declare function resolveLayoutContextFromShell(pageProps: Record<string, unknown>, shellLayouts: LayoutShellEntry[]): LayoutComposeContext;
40
- /**
41
- * Resolves props for one layout entry, merging shell locals with an optional factory.
48
+ * A layout receives request data only through its factory, so server and browser render a tier from the same
49
+ * props. The factory sees `context.locals`, or empty `locals` when the context has none; the layout does not.
42
50
  */
43
51
  export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutComposeContext): Record<string, unknown>;
44
52
  /**
@@ -58,7 +66,7 @@ export declare function composeLayoutPageTree<P extends Record<string, unknown>>
58
66
  * Builds a layout tree from explicit document-shell layout entries.
59
67
  *
60
68
  * @remarks
61
- * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
69
+ * Use when the route renderer passes per-tier props, which the server resolved from each entry's `props` factory.
62
70
  * Shell `entry.props` are authoritative; page config normalization is not required.
63
71
  */
64
72
  export declare function composeLayoutPageTreeFromShell<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, shellLayouts: LayoutShellEntry[], options?: LayoutComposeOptions): ReactElement;
@@ -13,7 +13,10 @@ function toReactComponent(component) {
13
13
  return component;
14
14
  }
15
15
  /**
16
- * Reads request-scoped layout context from serialized page props.
16
+ * Reads the Params and Query of a layout context from serialized page props.
17
+ *
18
+ * @remarks
19
+ * Serialized page props never carry `locals`; a server render passes them in `options.context`.
17
20
  */
18
21
  export function resolveLayoutContext(pageProps) {
19
22
  const context = {};
@@ -23,45 +26,17 @@ export function resolveLayoutContext(pageProps) {
23
26
  if (pageProps.query !== undefined) {
24
27
  context.query = pageProps.query;
25
28
  }
26
- if (pageProps.locals !== undefined) {
27
- context.locals = pageProps.locals;
28
- }
29
29
  return context;
30
30
  }
31
31
  /**
32
- * Builds layout prop factory context from document-shell layout entries.
32
+ * Resolves props for one layout entry: what its `props` factory returns, or nothing.
33
33
  *
34
34
  * @remarks
35
- * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
36
- */
37
- export function resolveLayoutContextFromShell(pageProps, shellLayouts) {
38
- const context = {};
39
- if (pageProps.params !== undefined) {
40
- context.params = pageProps.params;
41
- }
42
- if (pageProps.query !== undefined) {
43
- context.query = pageProps.query;
44
- }
45
- for (const entry of shellLayouts) {
46
- if (entry.props !== undefined && Object.prototype.hasOwnProperty.call(entry.props, 'locals')) {
47
- context.locals = entry.props.locals;
48
- break;
49
- }
50
- }
51
- return context;
52
- }
53
- /**
54
- * Resolves props for one layout entry, merging shell locals with an optional factory.
35
+ * A layout receives request data only through its factory, so server and browser render a tier from the same
36
+ * props. The factory sees `context.locals`, or empty `locals` when the context has none; the layout does not.
55
37
  */
56
38
  export function resolveLayoutEntryProps(entry, context) {
57
- const shellProps = context.locals ? { locals: context.locals } : {};
58
- if (!entry.props) {
59
- return shellProps;
60
- }
61
- return {
62
- ...shellProps,
63
- ...entry.props(context),
64
- };
39
+ return entry.props ? entry.props({ ...context, locals: context.locals ?? {} }) : {};
65
40
  }
66
41
  /**
67
42
  * @remarks
@@ -90,7 +65,9 @@ export function composeLayoutPageTree(Page, pageProps, options) {
90
65
  if (layoutEntries && layoutEntries.length > 0) {
91
66
  return [...layoutEntries].reverse().reduce((children, entry, reverseIndex) => {
92
67
  const index = layoutEntries.length - 1 - reverseIndex;
93
- const layoutProps = resolveLayoutEntryProps(entry, context);
68
+ const layoutProps = options?.tierProps
69
+ ? (options.tierProps[index] ?? {})
70
+ : resolveLayoutEntryProps(entry, context);
94
71
  const tier = resolvePersistedTier?.(entry.component, index);
95
72
  const Layout = toTrackedReactComponent(tier?.layout ?? entry.component, index, tracker);
96
73
  const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
@@ -99,9 +76,9 @@ export function composeLayoutPageTree(Page, pageProps, options) {
99
76
  }
100
77
  const layouts = Page.config?.layouts;
101
78
  if (layouts && layouts.length > 0) {
102
- const layoutProps = context.locals ? { locals: context.locals } : {};
103
79
  return [...layouts].reverse().reduce((children, Layout, reverseIndex) => {
104
80
  const index = layouts.length - 1 - reverseIndex;
81
+ const layoutProps = options?.tierProps?.[index] ?? {};
105
82
  const tier = resolvePersistedTier?.(Layout, index);
106
83
  const ResolvedLayout = toTrackedReactComponent(tier?.layout ?? Layout, index, tracker);
107
84
  const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
@@ -118,7 +95,7 @@ function toTrackedReactComponent(component, index, tracker) {
118
95
  * Builds a layout tree from explicit document-shell layout entries.
119
96
  *
120
97
  * @remarks
121
- * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
98
+ * Use when the route renderer passes per-tier props, which the server resolved from each entry's `props` factory.
122
99
  * Shell `entry.props` are authoritative; page config normalization is not required.
123
100
  */
124
101
  export function composeLayoutPageTreeFromShell(Page, pageProps, shellLayouts, options) {