@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.27

package/src/types/public-types.ts

@@ -2,7 +2,7 @@ import type { Readable } from 'node:stream';
 import type { ApiResponseBuilder } from '../adapters/shared/api-response.ts';
 import type { BuildExecutor } from '../build/build-adapter.ts';
 import type { EcoBuildPlugin } from '../build/build-types.ts';
-import type { ComponentBoundaryRuntime } from '../route-renderer/orchestration/component-render-context.ts';
+import type { ForeignChildRuntime } from '../route-renderer/orchestration/component-render-context.ts';
 import type { EcoPageComponent } from '../eco/eco.types.ts';
 import type { EcoPagesAppConfig } from './internal-types.ts';
 import type { HmrStrategy } from '../hmr/hmr-strategy.ts';
@@ -31,7 +31,7 @@ export type {
 	StandardSchemaFailureResult,
 	StandardSchemaIssue,
 	InferOutput,
-	ComponentBoundaryRuntime,
+	ForeignChildRuntime,
 };
 
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
@@ -112,11 +112,6 @@ export interface DefaultHmrContext {
 	 */
 	getWatchedFiles(): Map<string, string>;
 
-	/**
-	 * Map of bare specifiers to runtime URLs for browser import resolution.
-	 */
-	getSpecifierMap(): Map<string, string>;
-
 	/**
 	 * Directory where HMR bundles are written.
 	 */
@@ -218,16 +213,6 @@ export interface IHmrManager {
 	 */
 	registerScriptEntrypoint(entrypointPath: string): Promise<string>;
 
-	/**
-	 * Registers mappings from bare specifiers to runtime URLs.
-	 *
-	 * @remarks
-	 * This is the shared registration seam for integration-owned runtime alias
-	 * maps. The registry may later back a broader import-map-style facility, but
-	 * the mappings themselves remain integration-owned.
-	 */
-	registerSpecifierMap(map: Record<string, string>): void;
-
 	/**
 	 * Registers a custom HMR strategy.
 	 */
@@ -263,11 +248,6 @@ export interface IHmrManager {
 	 */
 	getWatchedFiles(): Map<string, string>;
 
-	/**
-	 * Gets the registered bare-specifier map.
-	 */
-	getSpecifierMap(): Map<string, string>;
-
 	/**
 	 * Gets the HMR dist directory.
 	 */
@@ -783,7 +763,7 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
 	pageProps?: Record<string, unknown>;
 	cacheStrategy?: CacheStrategy;
 	pageLocals?: RequestLocals;
-	boundaryPlan?: BoundaryPlan;
+	ownershipPlan?: OwnershipPlan;
 };
 
 /**
@@ -824,19 +804,34 @@ export interface PagePackageResult {
 	dynamicChunks: ProcessedAsset[];
 }
 
-export type BoundaryValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
+/**
+ * Page-scoped browser output planned before final HTML packaging.
+ *
+ * The initial seam keeps the graph payload intentionally small: integrations
+ * return the processed assets that belong to the Page browser graph, while the
+ * surrounding route pipeline remains free to evolve toward richer entry/lazy/
+ * shared chunk structure later.
+ */
+export interface PageBrowserGraphResult {
+	/**
+	 * Processed assets owned by the current Page browser graph.
+	 */
+	assets: ProcessedAsset[];
+}
+
+export type OwnershipValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
 
-export interface BoundaryValidationError {
-	code: BoundaryValidationErrorCode;
+export interface OwnershipValidationError {
+	code: OwnershipValidationErrorCode;
 	message: string;
 	componentId?: string;
 	componentFile?: string;
 	integrationName?: string;
 }
 
-export type BoundaryPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
+export type OwnershipPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
 
-export interface BoundaryOwnership {
+export interface IntegrationOwnership {
 	integrationName: string;
 	componentId: string;
 	componentFile?: string;
@@ -844,35 +839,35 @@ export interface BoundaryOwnership {
 	isForeignToParent: boolean;
 }
 
-export interface BoundaryPlanNode {
+export interface OwnershipPlanNode {
 	id: string;
-	source: BoundaryPlanNodeSource;
-	ownership: BoundaryOwnership;
-	children: BoundaryPlanNode[];
+	source: OwnershipPlanNodeSource;
+	ownership: IntegrationOwnership;
+	children: OwnershipPlanNode[];
 	declaredDependenciesValid: boolean;
 }
 
-export interface BoundaryPlan {
-	root: BoundaryPlanNode;
+export interface OwnershipPlan {
+	root: OwnershipPlanNode;
 	rendererNames: string[];
 	foreignEdgeCount: number;
 	hasValidationErrors: boolean;
-	validationErrors: BoundaryValidationError[];
+	validationErrors: OwnershipValidationError[];
 }
 
-export type BoundaryAttachmentPolicy = { kind: 'none' } | { kind: 'first-element' };
+export type ForeignSubtreeAttachmentPolicy = { kind: 'none' } | { kind: 'first-element' };
 
-export interface BoundaryRenderPayload {
+export interface ForeignSubtreeRenderPayload {
 	html: string;
 	assets: ProcessedAsset[];
 	rootTag?: string;
 	rootAttributes?: Record<string, string>;
-	attachmentPolicy: BoundaryAttachmentPolicy;
+	attachmentPolicy: ForeignSubtreeAttachmentPolicy;
 	integrationName: string;
 }
 
 /**
- * Shared execution-scoped context threaded through component boundary renders.
+ * Shared execution-scoped context threaded through foreign-child renders.
  *
  * Integrations can extend this with renderer-local runtime keys, but the cache
  * and optional component instance identity are shared across all renderers.
@@ -1144,6 +1139,18 @@ export interface ApiHandlerContext<TRequest extends Request = Request, TServer =
 	headers?: unknown;
 }
 
+/**
+ * Context available to file-route page middleware.
+ *
+ * Page middleware can mutate locals, short-circuit the request, and use the
+ * response helpers, but final document rendering stays owned by the page route
+ * execution path.
+ */
+export interface FileRouteMiddlewareContext<TRequest extends Request = Request, TServer = any> extends Omit<
+	ApiHandlerContext<TRequest, TServer>,
+	'render' | 'renderPartial'
+> {}
+
 /**
  * Next function for middleware chain.
  * Call to continue to the next middleware or final handler.
@@ -1185,6 +1192,15 @@ export type Middleware<
 	TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
 > = (context: TContext, next: MiddlewareNext) => Promise<Response> | Response;
 
+/**
+ * Middleware contract for file-based page routes.
+ */
+export type FileRouteMiddleware<
+	TRequest extends Request = Request,
+	TServer = any,
+	TContext extends FileRouteMiddlewareContext<TRequest, TServer> = FileRouteMiddlewareContext<TRequest, TServer>,
+> = (context: TContext, next: MiddlewareNext) => Promise<Response> | Response;
+
 /**
  * Helper type for defining middleware with extended context.
  * Automatically infers TRequest and TServer from the provided context type.

package/src/watchers/project-watcher.test-helpers.ts

@@ -10,21 +10,22 @@ export const createMockHmrManager = (): IHmrManager =>
 		setPlugins: vi.fn(() => {}),
 		registerEntrypoint: vi.fn(async () => ''),
 		registerScriptEntrypoint: vi.fn(async () => ''),
-		registerSpecifierMap: vi.fn(() => {}),
 		registerStrategy: vi.fn(() => {}),
 		isEnabled: vi.fn(() => true),
 		getOutputUrl: vi.fn(() => undefined),
 		getWatchedFiles: vi.fn(() => new Map()),
-		getSpecifierMap: vi.fn(() => new Map()),
 		getDistDir: vi.fn(() => ''),
 		getPlugins: vi.fn(() => []),
 		getDefaultContext: vi.fn(() => ({
 			getWatchedFiles: () => new Map(),
-			getSpecifierMap: () => new Map(),
 			getDistDir: () => '',
 			getPlugins: () => [],
 			getSrcDir: () => '',
 			getLayoutsDir: () => '',
+			getPagesDir: () => '',
+			getBuildExecutor: () => ({ build: vi.fn(async () => ({ success: true, logs: [], outputs: [] })) }),
+			getBrowserBundleService: () => ({ bundle: vi.fn(async () => ({ success: true, logs: [], outputs: [] })) }),
+			importServerModule: vi.fn(async () => ({})),
 		})),
 	}) as unknown as IHmrManager;
 

package/src/route-renderer/orchestration/boundary-planning.service.ts

@@ -1,146 +0,0 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type {
-	BoundaryPlan,
-	BoundaryPlanNode,
-	BoundaryPlanNodeSource,
-	BoundaryValidationError,
-	EcoComponent,
-} from '../../types/public-types.ts';
-
-type BoundaryPlanBuildInput = {
-	routeFile: string;
-	currentIntegrationName: string;
-	HtmlTemplate: EcoComponent;
-	Layout?: EcoComponent;
-	Page: EcoComponent;
-};
-
-type BoundaryPlanBuildEntry = {
-	component: EcoComponent;
-	source: Extract<BoundaryPlanNodeSource, 'page' | 'layout' | 'html-template'>;
-};
-
-/**
- * Builds a declared ownership plan from the component dependency graph.
- *
- * The plan is intentionally conservative: it reflects declared component
- * dependencies available during render preparation and records diagnostics for
- * foreign ownership edges that cannot be validated against registered
- * integrations or stable component metadata.
- */
-export class BoundaryPlanningService {
-	private readonly appConfig: EcoPagesAppConfig;
-	private nextSyntheticId = 0;
-
-	constructor(appConfig: EcoPagesAppConfig) {
-		this.appConfig = appConfig;
-	}
-
-	buildPlan(input: BoundaryPlanBuildInput): BoundaryPlan {
-		this.nextSyntheticId = 0;
-
-		const validationErrors: BoundaryValidationError[] = [];
-		const rendererNames = new Set<string>([input.currentIntegrationName]);
-		let foreignEdgeCount = 0;
-
-		const buildNode = (
-			component: EcoComponent,
-			source: Exclude<BoundaryPlanNodeSource, 'route'>,
-			parentIntegrationName: string,
-			lineage: Set<object>,
-		): BoundaryPlanNode => {
-			const integrationName =
-				component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
-			const componentMeta = component.config?.__eco;
-			const isForeignToParent = integrationName !== parentIntegrationName;
-			const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${(this.nextSyntheticId += 1)}`;
-
-			rendererNames.add(integrationName);
-
-			if (isForeignToParent) {
-				foreignEdgeCount += 1;
-
-				if (!componentMeta) {
-					validationErrors.push({
-						code: 'MISSING_COMPONENT_METADATA',
-						message: `[ecopages] Foreign boundary "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
-						componentId,
-						integrationName,
-					});
-				}
-
-				if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
-					validationErrors.push({
-						code: 'UNKNOWN_INTEGRATION_OWNER',
-						message: `[ecopages] Foreign boundary "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
-						componentId,
-						componentFile: componentMeta?.file,
-						integrationName,
-					});
-				}
-			}
-
-			const nextLineage = new Set(lineage);
-			nextLineage.add(component);
-			const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
-				if (!child || nextLineage.has(child)) {
-					return [];
-				}
-
-				return [buildNode(child, 'dependency', integrationName, nextLineage)];
-			});
-
-			return {
-				id: componentId,
-				source,
-				ownership: {
-					integrationName,
-					componentId,
-					componentFile: componentMeta?.file,
-					isPageEntry: source === 'page',
-					isForeignToParent,
-				},
-				children,
-				declaredDependenciesValid: true,
-			};
-		};
-
-		const roots: BoundaryPlanBuildEntry[] = [
-			{ component: input.HtmlTemplate, source: 'html-template' },
-			...(input.Layout ? [{ component: input.Layout, source: 'layout' as const }] : []),
-			{ component: input.Page, source: 'page' },
-		];
-
-		const root: BoundaryPlanNode = {
-			id: `route:${input.routeFile}`,
-			source: 'route',
-			ownership: {
-				integrationName: input.currentIntegrationName,
-				componentId: `route:${input.routeFile}`,
-				componentFile: input.routeFile,
-				isPageEntry: false,
-				isForeignToParent: false,
-			},
-			children: roots.map(({ component, source }) =>
-				buildNode(component, source, input.currentIntegrationName, new Set()),
-			),
-			declaredDependenciesValid: validationErrors.length === 0,
-		};
-
-		return {
-			root,
-			rendererNames: Array.from(rendererNames),
-			foreignEdgeCount,
-			hasValidationErrors: validationErrors.length > 0,
-			validationErrors,
-		};
-	}
-
-	private isRegisteredIntegration(integrationName: string, currentIntegrationName: string): boolean {
-		if (integrationName === currentIntegrationName) {
-			return true;
-		}
-
-		return this.appConfig.integrations.some((integration) => integration.name === integrationName);
-	}
-}

package/src/route-renderer/orchestration/page-packaging.service.ts

@@ -1,85 +0,0 @@
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
-import type { PagePackageResult } from '../../types/public-types.ts';
-
-/**
- * Creates the structured page package consumed by final HTML injection.
- *
- * This first pass is intentionally behavior-preserving. It establishes the
- * packaging seam while forwarding the current flat processed asset list.
- */
-export class PagePackagingService {
-	/**
-	 * Partitions processed assets into the page-level groups used during final
-	 * HTML injection and post-processing.
-	 */
-	createPagePackage(assets: ProcessedAsset[]): PagePackageResult {
-		const inlineAssets: ProcessedAsset[] = [];
-		const separateAssets: ProcessedAsset[] = [];
-		const dynamicChunks: ProcessedAsset[] = [];
-		let pageScript: ProcessedAsset | undefined;
-		let pageStylesheet: ProcessedAsset | undefined;
-
-		for (const asset of assets) {
-			if (asset.inline) {
-				inlineAssets.push(asset);
-				continue;
-			}
-
-			if (asset.packageRole === 'dynamic-chunk') {
-				dynamicChunks.push(asset);
-				continue;
-			}
-
-			if (!pageScript && asset.packageRole === 'page-script') {
-				pageScript = asset;
-				continue;
-			}
-
-			if (!pageStylesheet && asset.packageRole === 'page-style') {
-				pageStylesheet = asset;
-				continue;
-			}
-
-			if (asset.packageRole === 'keep-separate' || asset.packageRole === 'runtime') {
-				separateAssets.push(asset);
-				continue;
-			}
-
-			if (!pageScript && asset.kind === 'script' && !asset.excludeFromHtml) {
-				pageScript = asset;
-				continue;
-			}
-
-			if (!pageStylesheet && asset.kind === 'stylesheet') {
-				pageStylesheet = asset;
-				continue;
-			}
-
-			separateAssets.push(asset);
-		}
-
-		const htmlAssets = assets.filter((asset) => this.shouldIncludeInHtml(asset));
-
-		return {
-			assets,
-			htmlAssets,
-			pageScript,
-			pageStylesheet,
-			inlineAssets,
-			separateAssets,
-			dynamicChunks,
-		};
-	}
-
-	private shouldIncludeInHtml(asset: ProcessedAsset): boolean {
-		if (asset.excludeFromHtml) {
-			return false;
-		}
-
-		if (asset.packageRole === 'runtime') {
-			return false;
-		}
-
-		return true;
-	}
-}

package/src/route-renderer/orchestration/render-execution.service.test.ts

@@ -1,196 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { getComponentRenderContext } from './component-render-context.ts';
-import type {
-	EcoComponent,
-	IntegrationRendererRenderOptions,
-	RouteRendererBody,
-	RouteRendererOptions,
-} from '../../types/public-types.ts';
-import { RenderExecutionService } from './render-execution.service.ts';
-
-describe('RenderExecutionService', () => {
-	it('captures streamed render bodies before final HTML handling', async () => {
-		const service = new RenderExecutionService();
-		const encoder = new TextEncoder();
-
-		const result = await service.captureHtmlRender(
-			async () =>
-				new ReadableStream({
-					start(controller) {
-						controller.enqueue(encoder.encode('<html><body><main>Streamed</main></body></html>'));
-						controller.close();
-					},
-				}) as unknown as BodyInit,
-		);
-
-		expect(result.body).toBeInstanceOf(ReadableStream);
-		expect(result.html).toContain('<main>Streamed</main>');
-	});
-
-	it('preserves streamed bodies when no boundary resolution or attribute stamping is required', async () => {
-		const service = new RenderExecutionService();
-		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
-		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
-		const encoder = new TextEncoder();
-
-		const result = await service.execute(
-			{
-				file: '/app/pages/index.tsx',
-				params: {},
-				query: {},
-			} as unknown as RouteRendererOptions,
-			{
-				prepareRenderOptions: async () =>
-					({
-						HtmlTemplate,
-						Page,
-						cacheStrategy: { revalidate: 60 },
-					}) as unknown as IntegrationRendererRenderOptions<unknown>,
-				render: async () =>
-					new ReadableStream({
-						start(controller) {
-							controller.enqueue(encoder.encode('<html><body><main>Streamed</main></body></html>'));
-							controller.close();
-						},
-					}) as unknown as BodyInit,
-				getDocumentAttributes: () => undefined,
-				applyAttributesToHtmlElement: (html) => html,
-				applyAttributesToFirstBodyElement: (html) => html,
-				transformResponse: async (response) => response.body as RouteRendererBody,
-			},
-		);
-
-		expect(result.cacheStrategy).toEqual({ revalidate: 60 });
-		expect(result.body).toBeInstanceOf(ReadableStream);
-		expect(await new Response(result.body as BodyInit).text()).toContain('<main>Streamed</main>');
-	});
-
-	it('applies root and document attributes to fully resolved route HTML', async () => {
-		const service = new RenderExecutionService();
-		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
-		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
-
-		const result = await service.execute(
-			{
-				file: '/app/pages/index.tsx',
-				params: {},
-				query: {},
-			} as unknown as RouteRendererOptions,
-			{
-				prepareRenderOptions: async () =>
-					({
-						HtmlTemplate,
-						Page,
-						cacheStrategy: { revalidate: 60 },
-						componentRender: {
-							canAttachAttributes: true,
-							rootAttributes: { 'data-eco-component-id': 'eco-page-root' },
-						},
-					}) as unknown as IntegrationRendererRenderOptions<unknown>,
-				render: async () => '<html><body><main>Resolved</main></body></html>',
-				getDocumentAttributes: () => ({ 'data-eco-document-owner': 'react-router' }),
-				applyAttributesToHtmlElement: (html, attributes) =>
-					html.replace('<html', `<html data-eco-document-owner="${attributes['data-eco-document-owner']}"`),
-				applyAttributesToFirstBodyElement: (html, attributes) =>
-					html.replace('<main', `<main data-eco-component-id="${attributes['data-eco-component-id']}"`),
-				transformResponse: async (response) => await response.text(),
-			},
-		);
-
-		expect(result.cacheStrategy).toEqual({ revalidate: 60 });
-		expect(result.body).toContain('<html data-eco-document-owner="react-router"><body>');
-		expect(result.body).toContain('<main data-eco-component-id="eco-page-root">Resolved</main>');
-	});
-
-	it('throws when route HTML contains escaped unresolved boundary artifacts', async () => {
-		const service = new RenderExecutionService();
-		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
-		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
-
-		await expect(
-			service.execute(
-				{
-					file: '/app/pages/index.tsx',
-					params: {},
-					query: {},
-				} as unknown as RouteRendererOptions,
-				{
-					prepareRenderOptions: async () =>
-						({
-							HtmlTemplate,
-							Page,
-							cacheStrategy: 'dynamic',
-						}) as unknown as IntegrationRendererRenderOptions<unknown>,
-					render: async () =>
-						'<html><body>&amp;lt;eco-marker data-eco-node-id=&quot;n_2&quot; data-eco-component-ref=&quot;page-component&quot; data-eco-props-ref=&quot;p_2&quot;&amp;gt;&amp;lt;/eco-marker&amp;gt;</body></html>',
-					getDocumentAttributes: () => undefined,
-					applyAttributesToHtmlElement: (html) => html,
-					applyAttributesToFirstBodyElement: (html) => html,
-					transformResponse: async (response) => await response.text(),
-				},
-			),
-		).rejects.toThrow('Full-route unresolved-boundary fallback has been removed');
-	});
-
-	it('renders routes with no active component render context', async () => {
-		const service = new RenderExecutionService();
-		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
-		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
-
-		const result = await service.execute(
-			{
-				file: '/app/pages/index.tsx',
-				params: {},
-				query: {},
-			} as unknown as RouteRendererOptions,
-			{
-				prepareRenderOptions: async () =>
-					({
-						HtmlTemplate,
-						Page,
-						cacheStrategy: 'dynamic',
-					}) as unknown as IntegrationRendererRenderOptions<unknown>,
-				render: async () => {
-					expect(getComponentRenderContext()).toBeUndefined();
-					return '<html><body><main>Plain render</main></body></html>';
-				},
-				getDocumentAttributes: () => undefined,
-				applyAttributesToHtmlElement: (html) => html,
-				applyAttributesToFirstBodyElement: (html) => html,
-				transformResponse: async (response) => await response.text(),
-			},
-		);
-
-		expect(result.body).toContain('<main>Plain render</main>');
-	});
-
-	it('throws when route HTML returns unresolved boundary artifact HTML', async () => {
-		const service = new RenderExecutionService();
-		const HtmlTemplate = (() => '<html></html>') as EcoComponent<Record<string, unknown>>;
-		const Page = (() => '<main>Page</main>') as EcoComponent<Record<string, unknown>>;
-
-		await expect(
-			service.execute(
-				{
-					file: '/app/pages/index.tsx',
-					params: {},
-					query: {},
-				} as unknown as RouteRendererOptions,
-				{
-					prepareRenderOptions: async () =>
-						({
-							HtmlTemplate,
-							Page,
-							cacheStrategy: 'dynamic',
-						}) as unknown as IntegrationRendererRenderOptions<unknown>,
-					render: async () =>
-						'<html><body><eco-marker data-eco-node-id="n_1" data-eco-component-ref="unexpected-marker" data-eco-props-ref="p_1"></eco-marker></body></html>',
-					getDocumentAttributes: () => undefined,
-					applyAttributesToHtmlElement: (html) => html,
-					applyAttributesToFirstBodyElement: (html) => html,
-					transformResponse: async (response) => await response.text(),
-				},
-			),
-		).rejects.toThrow('Full-route unresolved-boundary fallback has been removed');
-	});
-});