@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.7

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

@@ -2,7 +2,8 @@
  * JavaScript HMR Strategy
  *
  * Handles hot module replacement for JavaScript and TypeScript entrypoints.
- * Bundles files, replaces bare specifiers, and injects HMR boilerplate.
+ * Bundles files, inspects the emitted output, and decides whether the browser
+ * can hot-accept the change or must reload.
  *
  * @module
  */
@@ -11,8 +12,9 @@ import path from 'node:path';
 import { fileSystem } from '@ecopages/file-system';
 import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy';
 import { appLogger } from '../../global/app-logger';
-import { defaultBuildAdapter } from '../../build/build-adapter.ts';
 import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.ts';
+import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
 
 /**
  * Context interface providing access to HmrManager state.
@@ -29,24 +31,7 @@ export interface JsHmrContext {
 	 */
 	getSpecifierMap(): Map<string, string>;
 
-	/**
-	 * Returns entrypoints impacted by a changed dependency path.
-	 *
-	 * @remarks
-	 * This hook is currently provided by the Node HMR manager where dependency
-	 * graph metadata is extracted from the Node/esbuild build adapter.
-	 */
-	getDependencyEntrypoints?(filePath: string): Set<string>;
-
-	/**
-	 * Stores latest dependency set for an entrypoint.
-	 *
-	 * @remarks
-	 * This hook is currently used only by the Node HMR manager to maintain a
-	 * reverse invalidation index. Runtimes that do not provide it keep rebuild-all
-	 * fallback semantics.
-	 */
-	setEntrypointDependencies?(entrypointPath: string, dependencies: string[]): void;
+	getEntrypointDependencyGraph(): EntrypointDependencyGraph;
 
 	/**
 	 * Directory where HMR bundles are written.
@@ -62,24 +47,53 @@ export interface JsHmrContext {
 	 * Absolute path to the source directory.
 	 */
 	getSrcDir(): string;
+
+	/**
+	 * Absolute path to the pages directory.
+	 */
+	getPagesDir(): string;
+
+	/**
+	 * Absolute path to the layouts directory.
+	 */
+	getLayoutsDir(): string;
+
+	/**
+	 * All configured route-template extensions across integrations.
+	 */
+	getTemplateExtensions(): string[];
+
+	/**
+	 * Browser bundler used to rebuild changed entrypoints.
+	 */
+	getBrowserBundleService(): BrowserBundleExecutor;
+
+	/**
+	 * Returns whether a watched entrypoint should be rebuilt by the generic JS strategy.
+	 *
+	 * @remarks
+	 * Integrations with higher-priority HMR strategies can use this to keep the
+	 * generic JS strategy from overwriting their emitted entrypoints when a shared
+	 * dependency changes.
+	 */
+	shouldProcessEntrypoint?(entrypointPath: string): boolean;
 }
 
 /**
  * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
  *
- * This strategy rebuilds all registered entrypoints when any file changes,
- * as we don't currently track dependencies. This is safe but inefficient.
- *
  * The processing steps are:
  * 1. Check if any entrypoints are registered
- * 2. Rebuild all entrypoints (the changed file could be a dependency)
- * 3. Replace bare specifiers with vendor URLs
+ * 2. Rebuild impacted entrypoints, or all watched entrypoints when no runtime
+ *    dependency graph is available
+ * 3. Emit rebuilt entrypoint bundles for browser delivery
  * 4. Inject generic HMR boilerplate
  * 5. Broadcast update events for each rebuilt entrypoint
  *
  * @remarks
- * Future enhancement: Track dependencies using Bun's transpiler API to only
- * rebuild affected entrypoints instead of all of them.
+ * Node can provide dependency-graph metadata, so this strategy can rebuild only
+ * the entrypoints impacted by a changed dependency. Runtimes that do not expose
+ * that metadata intentionally keep the rebuild-all fallback.
  *
  * @see https://bun.sh/docs/runtime/transpiler
  *
@@ -97,9 +111,11 @@ export interface JsHmrContext {
  */
 export class JsHmrStrategy extends HmrStrategy {
 	readonly type = HmrStrategyType.SCRIPT;
+	private context: JsHmrContext;
 
-	constructor(private context: JsHmrContext) {
+	constructor(context: JsHmrContext) {
 		super();
+		this.context = context;
 	}
 
 	/**
@@ -116,6 +132,10 @@ export class JsHmrStrategy extends HmrStrategy {
 		const watchedFiles = this.context.getWatchedFiles();
 		const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
 		const isInSrc = filePath.startsWith(this.context.getSrcDir());
+		const isRouteTemplate =
+			filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+		const isIntegrationTemplate =
+			isRouteTemplate && this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
 
 		if (watchedFiles.size === 0) {
 			return false;
@@ -125,12 +145,17 @@ export class JsHmrStrategy extends HmrStrategy {
 			return false;
 		}
 
+		if (isIntegrationTemplate) {
+			return false;
+		}
+
 		if (watchedFiles.has(filePath)) {
 			return true;
 		}
 
-		if (this.context.getDependencyEntrypoints) {
-			return this.context.getDependencyEntrypoints(filePath).size > 0;
+		const entrypointDependencyGraph = this.context.getEntrypointDependencyGraph();
+		if (entrypointDependencyGraph.supportsSelectiveInvalidation()) {
+			return entrypointDependencyGraph.getDependencyEntrypoints(filePath).size > 0;
 		}
 
 		return true;
@@ -157,21 +182,24 @@ export class JsHmrStrategy extends HmrStrategy {
 			return { type: 'none' };
 		}
 
-		const dependencyHits = this.context.getDependencyEntrypoints?.(filePath) ?? new Set<string>();
+		const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
 		const hasDependencyHit = dependencyHits.size > 0;
 		const impactedEntrypoints = hasDependencyHit
 			? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint))
 			: Array.from(watchedFiles.keys());
+		const buildableEntrypoints = impactedEntrypoints.filter(
+			(entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true,
+		);
 
 		if (!hasDependencyHit) {
 			appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
 		}
 
-		if (impactedEntrypoints.length === 0) {
+		if (buildableEntrypoints.length === 0) {
 			return { type: 'none' };
 		}
 
-		const buildResult = await this.bundleEntrypoints(impactedEntrypoints);
+		const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
 
 		if (!buildResult.success) {
 			return { type: 'none' };
@@ -180,18 +208,18 @@ export class JsHmrStrategy extends HmrStrategy {
 		const updates: string[] = [];
 		let reloadRequired = false;
 
-		for (const entrypoint of impactedEntrypoints) {
+		for (const entrypoint of buildableEntrypoints) {
 			const outputUrl = watchedFiles.get(entrypoint);
 			if (!outputUrl) continue;
 
-			if (buildResult.dependencies && this.context.setEntrypointDependencies) {
+			if (buildResult.dependencies) {
 				const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
-				this.context.setEntrypointDependencies(entrypoint, entrypointDeps);
+				this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
 			}
 
 			const srcDir = this.context.getSrcDir();
 			const relativePath = path.relative(srcDir, entrypoint);
-			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?)$/, '.js');
+			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
 			const outputPath = path.join(this.context.getDistDir(), relativePathJs);
 
 			const result = await this.processOutput(outputPath, outputUrl);
@@ -234,15 +262,14 @@ export class JsHmrStrategy extends HmrStrategy {
 		entrypoints: string[],
 	): Promise<{ success: boolean; dependencies?: Map<string, string[]> }> {
 		try {
-			const result = await defaultBuildAdapter.build({
+			const result = await this.context.getBrowserBundleService().bundle({
+				profile: 'hmr-entrypoint',
 				entrypoints,
 				outdir: this.context.getDistDir(),
 				outbase: this.context.getSrcDir(),
 				naming: '[dir]/[name]',
-				...defaultBuildAdapter.getTranspileOptions('hmr-entrypoint'),
 				plugins: this.context.getPlugins(),
 				minify: false,
-				external: ['react', 'react-dom'],
 			});
 
 			if (!result.success) {
@@ -265,7 +292,8 @@ export class JsHmrStrategy extends HmrStrategy {
 	}
 
 	/**
-	 * Processes bundled output by replacing specifiers and injecting HMR code.
+	 * Processes bundled output and determines whether the browser can hot-accept
+	 * the update or must fall back to a full reload.
 	 *
 	 * @param filepath - Path to the bundled output file
 	 * @param url - URL path for the bundled file
@@ -273,25 +301,15 @@ export class JsHmrStrategy extends HmrStrategy {
 	 */
 	private async processOutput(filepath: string, url: string): Promise<{ success: boolean; requiresReload: boolean }> {
 		try {
-			let code = await fileSystem.readFile(filepath);
+			const code = await fileSystem.readFile(filepath);
 
 			if (code.includes('/* [ecopages] hmr */')) {
-				/**
-				 * Already processed, assume it supports HMR if it has the header (legacy safety)
-				 * or check specifically for accept
-				 */
+				// Legacy safety: previously processed bundles already carry the marker.
 				return { success: true, requiresReload: !code.includes('import.meta.hot.accept') };
 			}
 
-			code = this.replaceBareSpecifiers(code);
-			await fileSystem.writeAsync(filepath, code);
-
 			appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
 
-			/**
-			 * Implicit HMR check: if the code explicitly accepts HMR, we broadcast update.
-			 * Otherwise, we must reload the page to ensure fresh execution (e.g. for Custom Elements or side effects).
-			 */
 			const hasHmrAccept = code.includes('import.meta.hot.accept');
 			return { success: true, requiresReload: !hasHmrAccept };
 		} catch (error) {
@@ -299,29 +317,4 @@ export class JsHmrStrategy extends HmrStrategy {
 			return { success: false, requiresReload: false };
 		}
 	}
-
-	/**
-	 * Replaces bare specifiers with vendor URLs.
-	 *
-	 * Handles both static imports and dynamic imports.
-	 *
-	 * @param code - The bundled code to transform
-	 * @returns The transformed code with vendor URLs
-	 */
-	private replaceBareSpecifiers(code: string): string {
-		const specifierMap = this.context.getSpecifierMap();
-
-		if (specifierMap.size === 0) {
-			return code;
-		}
-
-		let result = code;
-		for (const [bareSpec, vendorUrl] of specifierMap.entries()) {
-			const escaped = bareSpec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-			result = result.replace(new RegExp(`from\\s*["']${escaped}["']`, 'g'), `from "${vendorUrl}"`);
-			result = result.replace(new RegExp(`import\\(["']${escaped}["']\\)`, 'g'), `import("${vendorUrl}")`);
-		}
-
-		return result;
-	}
 }

package/src/index.ts

@@ -2,4 +2,4 @@ export type * from './public-types.ts';
 export type * from './eco/eco.types.ts';
 export { eco } from './eco/eco.ts';
 export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.ts';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from './define-api-handler.ts';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.ts';

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

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import HtmlTemplate from '../../../__fixtures__/app/src/includes/html.ghtml.js';
+import { FIXTURE_APP_PROJECT_DIR } from '../../../__fixtures__/constants.js';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { GhtmlRenderer } from './ghtml-renderer.ts';
+
+const appConfig = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+const metadata = {
+	title: 'Ecopages',
+	description: 'Ecopages',
+};
+
+const pageBody = '<body>Hello World</body>';
+
+const rendererContext = {
+	appConfig,
+} as unknown as any;
+
+describe('GhtmlRenderer', () => {
+	it('should render the page', async () => {
+		const renderer = new GhtmlRenderer(rendererContext);
+
+		renderer
+			.render({
+				params: {},
+				query: {},
+				props: {},
+				file: 'file',
+				metadata,
+				Page: async () => pageBody,
+				resolvedDependencies: [],
+				HtmlTemplate,
+			})
+			.then((body) => {
+				expect(body).toContain('<!DOCTYPE html>');
+				expect(body).toContain('<body>Hello World</body>');
+				expect(body).toContain('<title>Ecopages</title>');
+				expect(body).toContain('<meta name="description" content="Ecopages" />');
+			});
+	});
+
+	it('should throw an error if the page fails to render', async () => {
+		const renderer = new GhtmlRenderer(rendererContext);
+
+		renderer
+			.render({
+				params: {},
+				query: {},
+				props: {},
+				file: 'file',
+				resolvedDependencies: [],
+				metadata,
+				Page: async () => {
+					throw new Error('Page failed to render');
+				},
+				HtmlTemplate,
+			})
+			.catch((error) => {
+				expect(error.message).toBe('Error rendering page: Page failed to render');
+			});
+	});
+});

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

@@ -10,7 +10,10 @@ import type {
 	PageMetadataProps,
 	RouteRendererBody,
 } from '../../public-types.ts';
-import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/integration-renderer.ts';
+import {
+	IntegrationRenderer,
+	type RenderToResponseContext,
+} from '../../route-renderer/orchestration/integration-renderer.ts';
 import { GHTML_PLUGIN_NAME } from './ghtml.plugin.ts';
 
 /**

package/src/internal-types.ts

@@ -1,18 +1,17 @@
 import type { EcoBuildPlugin } from './build/build-types.ts';
+import type { AppBuildManifest } from './build/build-manifest.ts';
+import type { BuildAdapter, BuildExecutor } from './build/build-adapter.ts';
 import type { IntegrationPlugin } from './plugins/integration-plugin.ts';
 import type { Processor } from './plugins/processor.ts';
 import type { PageMetadataProps } from './public-types.ts';
-import type { FSRouter } from './router/fs-router.ts';
+import type { FSRouter } from './router/server/fs-router.ts';
 import type { CacheConfig } from './services/cache/cache.types.ts';
-
-/**
- * The templates used to build the pages and loaded via the includes directory.
- */
-export type IncludesTemplates = {
-	head: string;
-	html: string;
-	seo: string;
-};
+import type { DevGraphService } from './services/runtime-state/dev-graph.service.ts';
+import type { EntrypointDependencyGraph } from './services/runtime-state/entrypoint-dependency-graph.service.ts';
+import type { NodeRuntimeManifest } from './services/runtime-manifest/node-runtime-manifest.service.ts';
+import type { RuntimeSpecifierRegistry } from './services/runtime-state/runtime-specifier-registry.service.ts';
+import type { ServerInvalidationState } from './services/runtime-state/server-invalidation-state.service.ts';
+import type { ServerModuleTranspiler } from './services/module-loading/server-module-transpiler.service.ts';
 
 export interface RobotsPreference {
 	/**
@@ -61,20 +60,22 @@ export type EcoPagesAppConfig = {
 	 * @default "layouts"
 	 */
 	layoutsDir: string;
-	/**
-	 * The templates used for the pages
-	 * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
-	 */
-	includesTemplates: IncludesTemplates;
-	/** Error 404 page
-	 * @default "404.kita.tsx"
-	 */
-	error404Template: string;
 	/**
 	 * The directory where the output will be located
 	 * @default "dist"
 	 */
 	distDir: string;
+	/**
+	 * The directory where internal runtime and build artifacts are stored.
+	 *
+	 * @remarks
+	 * This directory is not intended for deployment. It owns transpiled server
+	 * modules, runtime manifests, and processor caches so `distDir` can remain a
+	 * clean export tree.
+	 *
+	 * @default ".eco"
+	 */
+	workDir: string;
 	/**
 	 * The templates extensions based on the integrations
 	 */
@@ -109,6 +110,7 @@ export type EcoPagesAppConfig = {
 		config: string;
 		componentsDir: string;
 		distDir: string;
+		workDir: string;
 		includesDir: string;
 		layoutsDir: string;
 		pagesDir: string;
@@ -131,6 +133,24 @@ export type EcoPagesAppConfig = {
 	 * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
 	 */
 	cache?: CacheConfig;
+	/**
+	 * Runtime-owned services attached after config construction.
+	 *
+	 * These values are internal implementation details used to thread per-app
+	 * executors and similar runtime state through the system without relying on
+	 * process-global registries.
+	 */
+	runtime?: {
+		buildAdapter?: BuildAdapter;
+		buildManifest?: AppBuildManifest;
+		buildExecutor?: BuildExecutor;
+		devGraphService?: DevGraphService;
+		entrypointDependencyGraph?: EntrypointDependencyGraph;
+		nodeRuntimeManifest?: NodeRuntimeManifest;
+		runtimeSpecifierRegistry?: RuntimeSpecifierRegistry;
+		serverInvalidationState?: ServerInvalidationState;
+		serverModuleTranspiler?: ServerModuleTranspiler;
+	};
 	/**
 	 * Experimental features.
 	 */

package/src/plugins/README.md

@@ -0,0 +1,34 @@
+# Plugin Contracts
+
+This directory contains the authoring contracts for Ecopages integrations, processors, and related plugin-facing runtime declarations.
+
+## Purpose
+
+The plugin layer defines what packages are allowed to declare about themselves, while core retains orchestration ownership.
+
+These contracts are responsible for:
+
+- integration registration and lifecycle hooks
+- processor registration and asset capability declaration
+- runtime capability declaration and validation input
+- shared build-plugin bridge types used by integrations and processors
+
+## Main Files
+
+- `integration-plugin.ts`: framework-semantics contract for render integrations
+- `processor.ts`: asset-transformation contract for processors
+- `runtime-capability.ts`: runtime compatibility declaration types
+- `eco-component-meta-plugin.ts`: shared metadata transform used by core loading/build paths
+
+## Ownership Rules
+
+- Integrations own rendering semantics, hydration behavior, and integration-specific HMR strategy.
+- Processors own asset semantics, cache ownership, and processor-specific watch behavior.
+- Core owns lifecycle ordering, startup orchestration, and manifest assembly.
+
+## Lifecycle Summary
+
+1. Config build validates and prepares plugin contributions.
+2. Core seals the app-owned build manifest.
+3. Runtime startup calls runtime-only setup hooks.
+4. Request-time rendering and development invalidation reuse those finalized contracts.

package/src/plugins/alias-resolver-plugin.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import type { EcoBuildOnResolveResult } from '../build/build-types.ts';
+import { createAliasResolverPlugin } from './alias-resolver-plugin.ts';
+
+test('createAliasResolverPlugin resolves @ aliases to concrete barrel targets', async () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'ecopages-alias-resolver-'));
+	const srcDir = path.join(rootDir, 'src');
+	const layoutDir = path.join(srcDir, 'layouts', 'base-layout');
+	fs.mkdirSync(layoutDir, { recursive: true });
+	fs.writeFileSync(path.join(layoutDir, 'base-layout.kita.tsx'), 'export const BaseLayout = {};\n', 'utf8');
+	fs.writeFileSync(path.join(layoutDir, 'index.ts'), "export * from './base-layout.kita';\n", 'utf8');
+
+	try {
+		const registrations: Array<{
+			filter: RegExp;
+			callback: (args: {
+				path: string;
+			}) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>;
+		}> = [];
+		const plugin = createAliasResolverPlugin(srcDir);
+
+		plugin.setup({
+			onResolve(options, callback) {
+				registrations.push({ filter: options.filter, callback });
+			},
+			onLoad() {},
+			module() {},
+		});
+
+		assert.equal(registrations.length, 1);
+		assert.deepEqual(await registrations[0]?.callback({ path: '@/layouts/base-layout' }), {
+			path: path.join(layoutDir, 'base-layout.kita.tsx'),
+		});
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

package/src/plugins/alias-resolver-plugin.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import type { EcoBuildPlugin } from '../build/build-types.ts';
 
@@ -6,7 +6,9 @@ const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.m
 
 function findResolvablePath(candidate: string): string | undefined {
 	if (path.extname(candidate)) {
-		return existsSync(candidate) ? candidate : undefined;
+		if (existsSync(candidate)) {
+			return candidate;
+		}
 	}
 
 	for (const extension of RESOLVABLE_EXTENSIONS) {
@@ -26,6 +28,22 @@ function findResolvablePath(candidate: string): string | undefined {
 	return undefined;
 }
 
+function resolveAliasedBarrelTarget(resolvedPath: string): string {
+	if (!path.basename(resolvedPath).startsWith('index.')) {
+		return resolvedPath;
+	}
+
+	const source = readFileSync(resolvedPath, 'utf8').trim();
+	const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+
+	if (!match?.[1]?.startsWith('.')) {
+		return resolvedPath;
+	}
+
+	const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+	return target ?? resolvedPath;
+}
+
 export function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin {
 	return {
 		name: 'ecopages-alias-resolver',
@@ -35,7 +53,7 @@ export function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin {
 				const resolved = findResolvablePath(candidate);
 
 				if (resolved) {
-					return { path: resolved };
+					return { path: resolveAliasedBarrelTarget(resolved) };
 				}
 
 				return {};