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

package/src/dev/host-runtime.ts

@@ -0,0 +1,34 @@
+import type { EcoPagesAppConfig } from '../types/public-types.ts';
+import {
+	DevelopmentInvalidationService,
+	type DevelopmentInvalidationPlan,
+} from '../services/invalidation/development-invalidation.service.ts';
+import { setHostModuleLoader } from '../services/module-loading/host-module-loader-registry.ts';
+
+export type HostRuntimeModuleLoader = (id: string) => Promise<unknown>;
+
+export interface DevelopmentHostRuntime {
+	registerHostModuleLoader(loader: HostRuntimeModuleLoader): void;
+	planFileChange(filePath: string): DevelopmentInvalidationPlan;
+	invalidateServerModules(changedFiles?: string[]): void;
+	resetRuntimeState(changedFiles?: string[]): void;
+}
+
+export function createDevelopmentHostRuntime(appConfig: EcoPagesAppConfig): DevelopmentHostRuntime {
+	const invalidationService = new DevelopmentInvalidationService(appConfig);
+
+	return {
+		registerHostModuleLoader(loader) {
+			setHostModuleLoader(loader);
+		},
+		planFileChange(filePath) {
+			return invalidationService.planFileChange(filePath);
+		},
+		invalidateServerModules(changedFiles) {
+			invalidationService.invalidateServerModules(changedFiles);
+		},
+		resetRuntimeState(changedFiles) {
+			invalidationService.resetRuntimeState(changedFiles);
+		},
+	};
+}

package/src/eco/eco.browser.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import type { Middleware } from '../types/public-types.ts';
+import type { FileRouteMiddleware } from '../types/public-types.ts';
 import { eco } from './eco.browser.ts';
 
 describe('browser eco facade', () => {
@@ -10,7 +10,7 @@ describe('browser eco facade', () => {
 
 		const staticPaths = async () => ({ paths: [{ params: { slug: 'intro' } }] });
 		const metadata = async () => ({ title: 'Docs', description: 'Docs page' });
-		const middleware: Middleware[] = [async (_ctx, next) => next()];
+		const middleware: FileRouteMiddleware[] = [async (_ctx, next) => next()];
 
 		const Page = eco.page({
 			layout: Layout,

package/src/eco/eco.browser.ts

@@ -4,10 +4,10 @@ import type {
 	EcoLayoutComponent,
 	EcoPagesElement,
 	EcoPageComponent,
+	FileRouteMiddleware,
 	GetMetadata,
 	GetStaticPaths,
 	GetStaticProps,
-	Middleware,
 	RequestPageContext,
 } from '../types/public-types.ts';
 import type { CacheStrategy } from '../services/cache/cache.types.ts';
@@ -38,7 +38,7 @@ function layout<E = EcoPagesElement>(options: LayoutOptions<E>): EcoLayoutCompon
 }
 
 function page<T, E>(
-	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: Middleware[] },
+	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: FileRouteMiddleware[] },
 ): EcoPageComponent<T> {
 	const {
 		layout: pageLayout,

package/src/eco/eco.test.ts

@@ -13,16 +13,16 @@ import type {
 } from '../types/public-types.ts';
 import type { EcoPagesAppConfig } from '../types/internal-types.ts';
 import {
-	type ComponentBoundaryRuntime,
+	type ForeignChildRuntime,
 	getComponentRenderContext,
 	runWithComponentRenderContext,
 } from '../route-renderer/orchestration/component-render-context.ts';
 
 const mockAppConfig = {} as EcoPagesAppConfig;
 
-function createResolvedBoundaryRuntime(targetIntegrations: string[], value: string): ComponentBoundaryRuntime {
+function createResolvedForeignChildRuntime(targetIntegrations: string[], value: string): ForeignChildRuntime {
 	return {
-		interceptBoundary: async ({ targetIntegration }: { targetIntegration?: string }) =>
+		interceptForeignChild: async ({ targetIntegration }: { targetIntegration?: string }) =>
 			targetIntegration !== undefined && targetIntegrations.includes(targetIntegration)
 				? ({ kind: 'resolved', value } as const)
 				: ({ kind: 'inline' } as const),
@@ -204,7 +204,7 @@ describe('eco namespace', () => {
 			expect(Component.config?.integration).toBe('lit');
 		});
 
-		test('should render inline when boundary context returns inline for a React component', async () => {
+		test('should render inline when the foreign-child runtime returns inline for a React component', async () => {
 			const ReactButton = eco.component({
 				integration: 'react',
 				__eco: {
@@ -225,7 +225,7 @@ describe('eco namespace', () => {
 			expect(execution.value).toBe('<button type="button">Click</button>');
 		});
 
-		test('should resolve foreign boundaries immediately when the runtime returns resolved output', async () => {
+		test('should resolve foreign children immediately when the runtime returns resolved output', async () => {
 			const ReactButton = eco.component({
 				integration: 'react',
 				__eco: {
@@ -239,7 +239,7 @@ describe('eco namespace', () => {
 			const execution = await runWithComponentRenderContext(
 				{
 					currentIntegration: 'lit',
-					boundaryRuntime: createResolvedBoundaryRuntime(
+					foreignChildRuntime: createResolvedForeignChildRuntime(
 						['react'],
 						'<aside>Resolved in owning renderer</aside>',
 					),

package/src/eco/eco.ts

@@ -9,10 +9,10 @@ import type {
 	EcoLayoutComponent,
 	EcoPagesElement,
 	EcoPageComponent,
+	FileRouteMiddleware,
 	GetMetadata,
 	GetStaticPaths,
 	GetStaticProps,
-	Middleware,
 	RequestLocals,
 	RequestPageContext,
 } from '../types/public-types.ts';
@@ -30,19 +30,19 @@ import type {
 } from './eco.types.ts';
 import {
 	finalizeComponentRender,
-	interceptComponentBoundary,
+	interceptForeignChild,
 } from '../route-renderer/orchestration/component-render-context.ts';
 import { isThenable } from '../route-renderer/orchestration/render-output.utils.ts';
 
 /**
- * Creates a component factory with lazy-trigger support and boundary-runtime
+ * Creates a component factory with lazy-trigger support and foreign-child-runtime
  * interception.
  *
  * Behavior:
  * - In normal render flow, returns `options.render(props)` with optional lazy
  *   trigger/script wrapping.
- * - When rendering under an active component boundary runtime and the current
- *   renderer-owned boundary runtime resolves the boundary immediately, returns
+ * - When rendering under an active foreign-child runtime and the current
+ *   renderer-owned foreign-child runtime resolves the foreign child immediately, returns
  *   that resolved output instead of rendering the component inline.
  *
  * @param options Component options for rendering and dependency declaration.
@@ -53,20 +53,20 @@ function createComponentFactory<P, E>(options: ComponentOptions<P, E>): EcoCompo
 	const comp: EcoComponent<P, E> = ((props: P) => {
 		const componentProps = (props ?? {}) as Record<string, unknown>;
 		const renderInline = () => finalizeComponentRender(comp, options.render(props)) as E;
-		const boundaryRender = interceptComponentBoundary({
+		const foreignChildRender = interceptForeignChild({
 			component: comp,
 			props: componentProps,
 			targetIntegration: integrationName,
 		});
 
-		if (isThenable<unknown | undefined>(boundaryRender)) {
-			return boundaryRender.then((resolvedBoundaryRender) =>
-				resolvedBoundaryRender !== undefined ? (resolvedBoundaryRender as E) : renderInline(),
+		if (isThenable<unknown | undefined>(foreignChildRender)) {
+			return foreignChildRender.then((resolvedForeignChildRender) =>
+				resolvedForeignChildRender !== undefined ? (resolvedForeignChildRender as E) : renderInline(),
 			) as E;
 		}
 
-		if (boundaryRender !== undefined) {
-			return boundaryRender as E;
+		if (foreignChildRender !== undefined) {
+			return foreignChildRender as E;
 		}
 
 		return renderInline();
@@ -129,7 +129,7 @@ function page<T = {}, E = EcoPagesElement, const K extends keyof RequestLocals =
  * @returns Eco page component.
  */
 function page<T, E>(
-	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: Middleware[] },
+	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: FileRouteMiddleware[] },
 ): EcoPageComponent<T> {
 	const { layout, dependencies, render, staticPaths, staticProps, metadata, cache, requires, middleware } = options;
 

package/src/eco/eco.types.ts

@@ -12,12 +12,12 @@ import type {
 	EcoLayoutComponent,
 	EcoPageLayoutComponent,
 	EcoPagesElement,
+	FileRouteMiddleware,
 	GetMetadata,
 	GetStaticPaths,
 	GetStaticProps,
 	HtmlTemplateProps,
 	LayoutProps,
-	Middleware,
 	RequestLocals,
 	RequestPageContext,
 } from '../types/public-types.ts';
@@ -119,7 +119,7 @@ interface PageOptionsWithMiddleware<T, E = EcoPagesElement> extends PageOptionsB
 	 * Request-time middleware for file-based routes.
 	 * Runs before rendering and can short-circuit by returning a Response.
 	 */
-	middleware: Middleware[];
+	middleware: FileRouteMiddleware[];
 }
 
 /**
@@ -164,7 +164,7 @@ export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<Request
 	metadata?: GetMetadata<T>;
 	cache?: CacheStrategy;
 	requires?: PageRequires;
-	middleware?: Middleware[];
+	middleware?: FileRouteMiddleware[];
 };
 
 /**

package/src/errors/index.ts

@@ -1,2 +1,3 @@
 export { HttpError } from './http-error.ts';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.ts';
+export { LocalsAccessError } from './locals-access-error.ts';

package/src/hmr/client/hmr-runtime.ts

@@ -52,7 +52,9 @@ interface HMRPayload {
 				break;
 			case 'layout-update': {
 				await waitForNavigationToSettle(navigationRuntime);
-				if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
+				if (
+					await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })
+				) {
 				} else {
 					location.reload();
 				}
@@ -107,7 +109,7 @@ interface HMRPayload {
 		}
 
 		const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
-		return handlerPaths.at(-1);
+		return handlerPaths[handlerPaths.length - 1];
 	}
 
 	async function waitForNavigationToSettle(navigationRuntime: ReturnType<typeof getEcoNavigationRuntime>) {

package/src/hmr/strategies/js-hmr-strategy.test.ts

@@ -12,7 +12,6 @@ const SRC_DIR = path.join(TMP_DIR, 'src');
 function createMockContext(overrides: Partial<JsHmrContext> = {}): JsHmrContext {
 	return {
 		getWatchedFiles: () => new Map(),
-		getSpecifierMap: () => new Map(),
 		getEntrypointDependencyGraph: () => new NoopDevGraphService(),
 		getDistDir: () => TMP_DIR,
 		getPlugins: () => [],

package/src/hmr/strategies/js-hmr-strategy.ts

@@ -26,11 +26,6 @@ export interface JsHmrContext {
 	 */
 	getWatchedFiles(): Map<string, string>;
 
-	/**
-	 * Map of bare specifiers to vendor URLs for import resolution.
-	 */
-	getSpecifierMap(): Map<string, string>;
-
 	getEntrypointDependencyGraph(): EntrypointDependencyGraph;
 
 	/**
@@ -101,7 +96,6 @@ export interface JsHmrContext {
  * ```typescript
  * const context = {
  *   getWatchedFiles: () => watchedFilesMap,
- *   getSpecifierMap: () => specifierMap,
  *   getDistDir: () => '/path/to/dist/_hmr',
  *   getPlugins: () => [],
  *   getSrcDir: () => '/path/to/src'

package/src/integrations/ghtml/ghtml-renderer.test.ts

@@ -3,7 +3,7 @@ import HtmlTemplate from '../../../__fixtures__/app/src/includes/html.ghtml.js';
 import { FIXTURE_APP_PROJECT_DIR } from '../../../__fixtures__/constants.js';
 import {
 	eco,
-	type BoundaryRenderPayload,
+	type ForeignSubtreeRenderPayload,
 	type EcoComponent,
 	type EcoPagesElement,
 	type HtmlTemplateProps,
@@ -121,7 +121,7 @@ describe('GhtmlRenderer', () => {
 		).rejects.toThrow('Error rendering page: Page failed to render');
 	});
 
-	it('should resolve deferred foreign layout content without unresolved boundary artifacts', async () => {
+	it('should resolve deferred foreign layout content without unresolved eco-marker artifacts', async () => {
 		const deferredPlugin = new DeferredPlugin();
 		const config = await new ConfigBuilder()
 			.setRootDir(FIXTURE_APP_PROJECT_DIR)
@@ -177,17 +177,17 @@ describe('GhtmlRenderer', () => {
 		expect(body).not.toContain('<eco-marker');
 	});
 
-	it('should expose the compatibility boundary payload contract', async () => {
+	it('should expose the compatibility foreign-subtree payload contract', async () => {
 		const renderer = createRenderer();
-		const Component = (async () => '<main>Boundary</main>') as EcoComponent<Record<string, unknown>>;
+		const Component = (async () => '<main>Foreign Subtree</main>') as EcoComponent<Record<string, unknown>>;
 
-		const result = await renderer.renderBoundary({
+		const result = await renderer.renderForeignSubtree({
 			component: Component,
 			props: {},
 		});
 
-		expect(result).toEqual<BoundaryRenderPayload>({
-			html: '<main>Boundary</main>',
+		expect(result).toEqual<ForeignSubtreeRenderPayload>({
+			html: '<main>Foreign Subtree</main>',
 			assets: [],
 			rootTag: 'main',
 			rootAttributes: undefined,

package/src/integrations/ghtml/ghtml-renderer.ts

@@ -30,22 +30,12 @@ export class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
 	name = GHTML_PLUGIN_NAME;
 
 	override async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
-		return this.renderStringComponentBoundaryWithQueuedForeignBoundaries(
+		return this.renderStringComponentWithQueuedForeignSubtrees(
 			input,
 			input.component as GhtmlViewFn<Record<string, unknown>>,
 		);
 	}
 
-	protected override createComponentBoundaryRuntime(options: {
-		boundaryInput: ComponentRenderInput;
-		rendererCache: Map<string, IntegrationRenderer<any>>;
-	}) {
-		return this.createQueuedBoundaryRuntime({
-			boundaryInput: options.boundaryInput,
-			rendererCache: options.rendererCache,
-		});
-	}
-
 	async render({
 		params,
 		query,

package/src/plugins/eco-component-meta-plugin.ts

@@ -26,7 +26,6 @@
  * @module eco-component-meta-plugin
  */
 
-import path from 'node:path';
 import { parseSync } from 'oxc-parser';
 import type { EcoBuildPlugin } from '../build/build-types.ts';
 import type { EcoPagesAppConfig } from '../types/internal-types.ts';

package/src/plugins/integration-plugin.test.ts

@@ -95,11 +95,10 @@ describe('IntegrationPlugin', () => {
 		await expect(plugin.teardown()).resolves.toBeUndefined();
 	});
 
-	it('should register runtime specifier maps through the base HMR setup', () => {
-		const registerSpecifierMap = vi.fn();
+	it('should register HMR strategies through the base HMR setup', () => {
+		const registerStrategy = vi.fn();
 		const hmrManager = {
-			registerSpecifierMap,
-			registerStrategy: vi.fn(),
+			registerStrategy,
 			registerEntrypoint: vi.fn(),
 			registerScriptEntrypoint: vi.fn(),
 			setPlugins: vi.fn(),
@@ -108,26 +107,22 @@ describe('IntegrationPlugin', () => {
 			broadcast: vi.fn(),
 			getOutputUrl: vi.fn(),
 			getWatchedFiles: vi.fn(() => new Map()),
-			getSpecifierMap: vi.fn(() => new Map()),
 			getDistDir: vi.fn(() => ''),
 			getPlugins: vi.fn(() => []),
 			getDefaultContext: vi.fn(),
 			handleFileChange: vi.fn(),
 		} satisfies IHmrManager;
 
-		const pluginWithRuntimeSpecifiers = new (class extends TestIntegrationPlugin {
-			override getRuntimeSpecifierMap(): Record<string, string> {
-				return {
-					'test-runtime': '/assets/vendors/test-runtime.js',
-				};
+		const strategy = { matches: vi.fn(() => false), process: vi.fn(), priority: 10, type: 'integration' } as any;
+		const pluginWithStrategy = new (class extends TestIntegrationPlugin {
+			override getHmrStrategy() {
+				return strategy;
 			}
 		})(config);
 
-		pluginWithRuntimeSpecifiers.setHmrManager(hmrManager);
+		pluginWithStrategy.setHmrManager(hmrManager);
 
-		expect(registerSpecifierMap).toHaveBeenCalledWith({
-			'test-runtime': '/assets/vendors/test-runtime.js',
-		});
+		expect(registerStrategy).toHaveBeenCalledWith(strategy);
 	});
 
 	it('should stamp the plugin integration name onto initialized renderers', () => {

package/src/plugins/integration-plugin.ts

@@ -5,15 +5,45 @@ import type { EcoPagesElement } from '../types/public-types.ts';
 import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.ts';
 import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.ts';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.ts';
+import { deepMerge } from '../utils/deep-merge.ts';
+import { invariant } from '../utils/invariant.ts';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
 
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
+export type {
+	EcoBuildLoader,
+	EcoBuildOnLoadArgs,
+	EcoBuildOnLoadResult,
+	EcoBuildOnResolveArgs,
+	EcoBuildOnResolveResult,
+	EcoBuildPlugin,
+	EcoBuildPluginBuilder,
+} from '../build/build-types.ts';
+
+/**
+ * Type-erased integration plugin stored in app-level registries.
+ *
+ * Ecopages keeps one heterogeneous integration list, while each plugin and
+ * renderer still owns its framework-specific render payload type internally.
+ */
+export type AnyIntegrationPlugin = IntegrationPlugin<unknown>;
 
 export const INTEGRATION_PLUGIN_ERRORS = {
 	NOT_INITIALIZED_WITH_APP_CONFIG: 'Plugin not initialized with app config',
 	NOT_INITIALIZED_WITH_ASSET_SERVICE: 'Plugin not initialized with asset dependency service',
 } as const;
 
+export function mergeIntegrationOptions<TDefaults, TOverrides>(
+	defaults: TDefaults,
+	overrides: TOverrides,
+): TDefaults & TOverrides {
+	return deepMerge(defaults, overrides);
+}
+
+export function assertIntegrationInvariant(condition: boolean, message?: string): asserts condition {
+	invariant(condition, message);
+}
+
 /**
  * Base configuration shared by all integration plugins.
  *
@@ -157,40 +187,22 @@ export abstract class IntegrationPlugin<C = EcoPagesElement> {
 	 * ```typescript
 	 * getHmrStrategy(): HmrStrategy {
 	 *   const context = this.hmrManager!.getDefaultContext();
-	 *   return new ReactHmrStrategy(context);
+	 *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeAliasMap });
 	 * }
 	 * ```
 	 */
 	getHmrStrategy?(): HmrStrategy | undefined;
 
-	/**
-	 * Returns bare-specifier mappings that should be registered in the active
-	 * runtime specifier registry.
-	 *
-	 * @remarks
-	 * Integrations that own browser runtime bundles can override this to expose
-	 * stable bare specifiers for client-side imports.
-	 *
-	 * Today these mappings are consumed by the development runtime and browser
-	 * bundle aliasing path. They are intentionally generic enough to grow into a
-	 * broader import-map-style facility later without moving framework-specific
-	 * map contents into core.
-	 */
-	getRuntimeSpecifierMap(): Record<string, string> {
-		return {};
-	}
-
 	/**
 	 * Attaches the shared HMR manager and registers integration-owned development hooks.
 	 *
 	 * @remarks
-	 * The default implementation registers both runtime bare-specifier mappings and
-	 * the optional integration HMR strategy. Integrations should override this only
-	 * when they need to extend that shared behavior rather than replace it.
+	 * The default implementation registers the optional integration HMR strategy.
+	 * Integrations should override this only when they need to extend that shared
+	 * behavior rather than replace it.
 	 */
 	setHmrManager(hmrManager: IHmrManager) {
 		this.hmrManager = hmrManager;
-		hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
 
 		const strategy = this.getHmrStrategy?.();
 		if (strategy) {

package/src/plugins/processor.ts

@@ -5,14 +5,31 @@ import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.t
 import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.ts';
 import { DEFAULT_ECOPAGES_WORK_DIR } from '../config/constants.ts';
 import { GENERATED_BASE_PATHS } from '../config/constants.ts';
+import { deepMerge } from '../utils/deep-merge.ts';
 import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
 
 export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
+export type {
+	EcoBuildLoader,
+	EcoBuildOnLoadArgs,
+	EcoBuildOnLoadResult,
+	EcoBuildOnResolveArgs,
+	EcoBuildOnResolveResult,
+	EcoBuildPlugin,
+	EcoBuildPluginBuilder,
+} from '../build/build-types.ts';
 
 export const PROCESSOR_ERRORS = {
 	CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
 } as const;
 
+export function mergeProcessorOptions<TDefaults, TOverrides>(
+	defaults: TDefaults,
+	overrides: TOverrides,
+): TDefaults & TOverrides {
+	return deepMerge(defaults, overrides);
+}
+
 function resolveGeneratedPath(
 	type: keyof typeof GENERATED_BASE_PATHS,
 	options: { root: string; module: string; subPath?: string },