@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

package/src/adapters/shared/hmr-entrypoint-registrar.ts

@@ -1,149 +0,0 @@
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import { appLogger } from '../../global/app-logger.ts';
-import { RESOLVED_ASSETS_DIR } from '../../constants.ts';
-
-/**
- * Shared runtime state used while registering HMR-owned entrypoints.
- */
-export interface HmrEntrypointRegistrarOptions {
-	/** Absolute source directory used to derive the emitted HMR path. */
-	srcDir: string;
-	/** Absolute distribution directory where HMR outputs are written. */
-	distDir: string;
-	/** In-flight registrations keyed by normalized absolute entrypoint path. */
-	entrypointRegistrations: Map<string, Promise<string>>;
-	/** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
-	watchedFiles: Map<string, string>;
-	/** Runtime-specific cleanup invoked when an entrypoint registration fails. */
-	clearFailedRegistration?: (entrypointPath: string) => void;
-	/** Development-only guardrail for integrations that never finish producing output. */
-	registrationTimeoutMs: number;
-}
-
-/**
- * Runtime-specific hooks required to materialize a single HMR entrypoint.
- */
-export interface HmrEntrypointRegistrationOptions {
-	/**
-	 * Emits the browser-consumable HMR artifact for an entrypoint.
-	 */
-	emit(entrypointPath: string, outputPath: string): Promise<void>;
-	/**
-	 * Creates the runtime-specific error raised when the emit hook completes without producing output.
-	 */
-	getMissingOutputError(entrypointPath: string, outputPath: string): Error;
-}
-
-/**
- * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
- *
- * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
- * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
- * apply the development timeout that prevents unresolved registrations from hanging navigation.
- * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
- * this shared registration flow.
- */
-export class HmrEntrypointRegistrar {
-	private readonly options: HmrEntrypointRegistrarOptions;
-
-	constructor(options: HmrEntrypointRegistrarOptions) {
-		this.options = options;
-	}
-
-	/**
-	 * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
-	 *
-	 * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-	 * integration only builds once per registration cycle.
-	 */
-	async registerEntrypoint(
-		entrypointPath: string,
-		registrationOptions: HmrEntrypointRegistrationOptions,
-	): Promise<string> {
-		const normalizedEntrypoint = path.resolve(entrypointPath);
-		const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
-		if (existingRegistration) {
-			return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
-		}
-
-		const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
-		this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
-
-		try {
-			return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
-		} catch (error) {
-			this.options.clearFailedRegistration?.(normalizedEntrypoint);
-			throw error;
-		} finally {
-			this.options.entrypointRegistrations.delete(normalizedEntrypoint);
-		}
-	}
-
-	private async registerEntrypointInternal(
-		entrypointPath: string,
-		registrationOptions: HmrEntrypointRegistrationOptions,
-	): Promise<string> {
-		if (this.options.watchedFiles.has(entrypointPath)) {
-			return this.options.watchedFiles.get(entrypointPath)!;
-		}
-
-		const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
-
-		this.options.watchedFiles.set(entrypointPath, outputUrl);
-		this.removeStaleEntrypointOutput(outputPath);
-
-		await registrationOptions.emit(entrypointPath, outputPath);
-
-		if (!fileSystem.exists(outputPath)) {
-			throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
-		}
-
-		return outputUrl;
-	}
-
-	private async awaitEntrypointRegistration(registration: Promise<string>, entrypointPath: string): Promise<string> {
-		if (process.env.NODE_ENV !== 'development') {
-			return await registration;
-		}
-
-		return await Promise.race([
-			registration,
-			new Promise<string>((_, reject) => {
-				setTimeout(() => {
-					reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
-				}, this.options.registrationTimeoutMs);
-			}),
-		]);
-	}
-
-	private getEntrypointOutput(entrypointPath: string): { outputPath: string; outputUrl: string } {
-		const relativePath = path.relative(this.options.srcDir, entrypointPath);
-		const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
-		const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-		const urlPath = encodedPathJs.split(path.sep).join('/');
-
-		return {
-			outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, '_hmr', urlPath)}`,
-			outputPath: path.join(this.options.distDir, urlPath),
-		};
-	}
-
-	private removeStaleEntrypointOutput(outputPath: string): void {
-		if (!fileSystem.exists(outputPath)) {
-			return;
-		}
-
-		try {
-			fileSystem.remove(outputPath);
-		} catch (error) {
-			appLogger.warn(
-				`[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`,
-			);
-		}
-	}
-
-	private encodeDynamicSegments(filepath: string): string {
-		return filepath.replace(/\[([^\]]+)\]/g, '_$1_');
-	}
-}

package/src/adapters/shared/hmr-html-response.ts

@@ -1,52 +0,0 @@
-import type { IHmrManager } from '../../public-types';
-
-const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
-const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};</script>`;
-
-/**
- * Returns whether a response is HTML and therefore eligible for development HMR
- * runtime injection.
- */
-export function isHtmlResponse(response: Response): boolean {
-	const contentType = response.headers.get('Content-Type');
-	return contentType !== null && contentType.startsWith('text/html');
-}
-
-/**
- * Returns whether HTML responses should receive the HMR runtime bootstrap.
- *
- * This is shared because filesystem page responses and adapter-level HTML
- * responses flow through different layers, but both need identical injection
- * behavior in watch mode.
- */
-export function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean {
-	return watch && hmrManager?.isEnabled() === true;
-}
-
-/**
- * Injects the development HMR runtime script into an HTML response if it is not
- * already present.
- *
- * The check is intentionally idempotent because an HTML response can pass
- * through more than one development-layer wrapper before reaching the client.
- */
-export async function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response> {
-	const html = await response.text();
-	if (html.includes(HMR_RUNTIME_IMPORT)) {
-		return new Response(html, {
-			status: response.status,
-			statusText: response.statusText,
-			headers: response.headers,
-		});
-	}
-
-	const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
-	const headers = new Headers(response.headers);
-	headers.delete('Content-Length');
-
-	return new Response(updatedHtml, {
-		status: response.status,
-		statusText: response.statusText,
-		headers,
-	});
-}

package/src/adapters/shared/render-context.ts

@@ -1,120 +0,0 @@
-import type { EcoComponent, RenderContext, RenderOptions, ResponseOptions } from '../../public-types.ts';
-import type {
-	IntegrationRenderer,
-	RenderToResponseContext,
-} from '../../route-renderer/orchestration/integration-renderer.ts';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
-import { invariant } from '../../utils/invariant.ts';
-
-export interface CreateRenderContextOptions {
-	integrations: IntegrationPlugin[];
-}
-
-/**
- * Merges request locals into component props as a dedicated 'locals' property.
- * This prevents naming conflicts and maintains type safety by keeping locals
- * separate from other props.
- *
- * @param props - The original component props
- * @param locals - Optional request-scoped locals from middleware
- * @returns Props with locals merged in, or original props if no locals provided
- */
-function mergePropsWithLocals<P>(props: P, locals: Record<string, unknown> | undefined): P {
-	if (!locals || typeof props !== 'object' || props === null) {
-		return props;
-	}
-	return { ...(props as Record<string, unknown>), locals } as P;
-}
-
-/**
- * Creates a render context for route handlers.
- * Provides render(), renderPartial(), json(), and html() methods that can be used
- * within route handlers to generate responses.
- *
- * @param options - Configuration options including available integrations
- * @returns A RenderContext object with methods for rendering views and creating responses
- */
-export function createRenderContext(options: CreateRenderContextOptions): RenderContext {
-	const { integrations } = options;
-
-	/**
-	 * Resolves the appropriate renderer for a given view component based on its integration.
-	 * Throws an error if the integration cannot be determined or is not found.
-	 */
-	const getRendererForView = <P>(view: EcoComponent<P>): IntegrationRenderer => {
-		const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
-		invariant(
-			!!integrationName,
-			'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.',
-		);
-
-		const integration = integrations.find((i) => i.name === integrationName);
-		invariant(!!integration, `No integration found for: ${integrationName}`);
-
-		return integration.initializeRenderer();
-	};
-
-	const renderContext: RenderContext = {
-		async render<P>(
-			this: { locals?: Record<string, unknown> } | undefined,
-			view: EcoComponent<P>,
-			props?: P,
-			renderOptions?: RenderOptions,
-		): Promise<Response> {
-			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
-			const mergedProps = mergePropsWithLocals<P>(props ?? ({} as P), locals);
-
-			const renderer = getRendererForView(view);
-			const ctx: RenderToResponseContext = {
-				partial: false,
-				status: renderOptions?.status,
-				headers: renderOptions?.headers,
-			};
-			return renderer.renderToResponse(view, mergedProps, ctx);
-		},
-
-		async renderPartial<P>(
-			this: { locals?: Record<string, unknown> } | undefined,
-			view: EcoComponent<P>,
-			props: P,
-			renderOptions?: RenderOptions,
-		): Promise<Response> {
-			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
-			const mergedProps = mergePropsWithLocals<P>(props, locals);
-
-			const renderer = getRendererForView(view);
-			const ctx: RenderToResponseContext = {
-				partial: true,
-				status: renderOptions?.status,
-				headers: renderOptions?.headers,
-			};
-			return renderer.renderToResponse(view, mergedProps, ctx);
-		},
-
-		json(data: unknown, responseOptions?: ResponseOptions): Response {
-			const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
-			if (responseOptions?.headers) {
-				const incomingHeaders = new Headers(responseOptions.headers);
-				incomingHeaders.forEach((value, key) => headers.set(key, value));
-			}
-			return new Response(JSON.stringify(data), {
-				status: responseOptions?.status ?? 200,
-				headers,
-			});
-		},
-
-		html(content: string, responseOptions?: ResponseOptions): Response {
-			const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8' });
-			if (responseOptions?.headers) {
-				const incomingHeaders = new Headers(responseOptions.headers);
-				incomingHeaders.forEach((value, key) => headers.set(key, value));
-			}
-			return new Response(content, {
-				status: responseOptions?.status ?? 200,
-				headers,
-			});
-		},
-	};
-
-	return renderContext;
-}

package/src/adapters/shared/runtime-bootstrap.d.ts

@@ -1,38 +0,0 @@
-import { type BuildExecutor } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
-import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../internal-types.js';
-/**
- * Installs and returns the app-owned runtime build executor used by adapter
- * startup and follow-up runtime work.
- */
-export declare function installSharedRuntimeBuildExecutor(appConfig: EcoPagesAppConfig, options: {
-    development: boolean;
-}): BuildExecutor;
-/**
- * Copies app public assets into dist and ensures the resolved assets directory
- * exists before request handling begins.
- */
-export declare function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
-/**
- * Runs runtime plugin setup against app-owned config/runtime state and optional
- * host plugin registration hooks.
- */
-export declare function initializeSharedRuntimePlugins(options: {
-    appConfig: EcoPagesAppConfig;
-    runtimeOrigin: string;
-    hmrManager?: IHmrManager;
-    onRuntimePlugin?: (plugin: unknown) => void;
-}): Promise<void>;
-/**
- * Starts shared project watching for runtime adapters.
- */
-export declare function startSharedProjectWatching(options: {
-    appConfig: EcoPagesAppConfig;
-    refreshRouterRoutesCallback: () => Promise<void>;
-    hmrManager: IHmrManager;
-    bridge: IClientBridge;
-}): Promise<void>;
-/**
- * Binds a runtime HMR manager to app-owned plugin and integration state.
- */
-export declare function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[];

package/src/adapters/shared/runtime-bootstrap.js

@@ -1,43 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { getAppBrowserBuildPlugins, setupAppRuntimePlugins } from "../../build/build-adapter.js";
-import { installAppRuntimeBuildExecutor } from "../../build/runtime-build-executor.js";
-import { RESOLVED_ASSETS_DIR } from "../../constants.js";
-import { ProjectWatcher } from "../../watchers/project-watcher.js";
-function installSharedRuntimeBuildExecutor(appConfig, options) {
-  return installAppRuntimeBuildExecutor(appConfig, options);
-}
-function prepareSharedRuntimePublicDir(appConfig) {
-  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
-  if (fileSystem.exists(srcPublicDir)) {
-    fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
-  }
-  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-}
-async function initializeSharedRuntimePlugins(options) {
-  await setupAppRuntimePlugins(options);
-}
-async function startSharedProjectWatching(options) {
-  const watcher = new ProjectWatcher({
-    config: options.appConfig,
-    refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
-    hmrManager: options.hmrManager,
-    bridge: options.bridge
-  });
-  await watcher.createWatcherSubscription();
-}
-function bindSharedRuntimeHmrManager(appConfig, hmrManager) {
-  const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
-  hmrManager.setPlugins(browserBuildPlugins);
-  for (const integration of appConfig.integrations) {
-    integration.setHmrManager(hmrManager);
-  }
-  return browserBuildPlugins;
-}
-export {
-  bindSharedRuntimeHmrManager,
-  initializeSharedRuntimePlugins,
-  installSharedRuntimeBuildExecutor,
-  prepareSharedRuntimePublicDir,
-  startSharedProjectWatching
-};

package/src/adapters/shared/runtime-bootstrap.ts

@@ -1,79 +0,0 @@
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import { getAppBrowserBuildPlugins, setupAppRuntimePlugins, type BuildExecutor } from '../../build/build-adapter.ts';
-import type { EcoBuildPlugin } from '../../build/build-types.ts';
-import { installAppRuntimeBuildExecutor } from '../../build/runtime-build-executor.ts';
-import { RESOLVED_ASSETS_DIR } from '../../constants.ts';
-import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../internal-types.ts';
-import { ProjectWatcher } from '../../watchers/project-watcher.ts';
-
-/**
- * Installs and returns the app-owned runtime build executor used by adapter
- * startup and follow-up runtime work.
- */
-export function installSharedRuntimeBuildExecutor(
-	appConfig: EcoPagesAppConfig,
-	options: { development: boolean },
-): BuildExecutor {
-	return installAppRuntimeBuildExecutor(appConfig, options);
-}
-
-/**
- * Copies app public assets into dist and ensures the resolved assets directory
- * exists before request handling begins.
- */
-export function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void {
-	const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
-
-	if (fileSystem.exists(srcPublicDir)) {
-		fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
-	}
-
-	fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
-}
-
-/**
- * Runs runtime plugin setup against app-owned config/runtime state and optional
- * host plugin registration hooks.
- */
-export async function initializeSharedRuntimePlugins(options: {
-	appConfig: EcoPagesAppConfig;
-	runtimeOrigin: string;
-	hmrManager?: IHmrManager;
-	onRuntimePlugin?: (plugin: unknown) => void;
-}): Promise<void> {
-	await setupAppRuntimePlugins(options);
-}
-
-/**
- * Starts shared project watching for runtime adapters.
- */
-export async function startSharedProjectWatching(options: {
-	appConfig: EcoPagesAppConfig;
-	refreshRouterRoutesCallback: () => Promise<void>;
-	hmrManager: IHmrManager;
-	bridge: IClientBridge;
-}): Promise<void> {
-	const watcher = new ProjectWatcher({
-		config: options.appConfig,
-		refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
-		hmrManager: options.hmrManager,
-		bridge: options.bridge,
-	});
-
-	await watcher.createWatcherSubscription();
-}
-
-/**
- * Binds a runtime HMR manager to app-owned plugin and integration state.
- */
-export function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[] {
-	const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
-	hmrManager.setPlugins(browserBuildPlugins);
-
-	for (const integration of appConfig.integrations) {
-		integration.setHmrManager(hmrManager);
-	}
-
-	return browserBuildPlugins;
-}