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

package/src/eco/lazy-injector-map.ts

@@ -1,120 +0,0 @@
-import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
-import type { ResolvedLazyScriptGroup } from '../public-types.ts';
-
-/**
- * Normalizes a comma-separated scripts string into absolute script URLs.
- *
- * @param scripts Comma-separated script paths.
- * @returns Normalized script path list.
- */
-function normalizeScripts(scripts: string): string[] {
-	return scripts
-		.split(',')
-		.map((scriptPath) => scriptPath.trim())
-		.filter(Boolean)
-		.map((scriptPath) => {
-			if (scriptPath.startsWith('/')) {
-				return scriptPath;
-			}
-
-			const normalizedRelativePath = scriptPath.replace(/^\/+/, '').replace(/^(\.\/)+/, '');
-			return `/${normalizedRelativePath}`;
-		});
-}
-
-/**
- * Deduplicates comma-separated values while preserving first-seen order.
- *
- * @param values CSV value list.
- * @returns A single normalized CSV string.
- */
-function dedupeCsvValues(values: string[]): string {
-	const seen = new Set<string>();
-
-	for (const value of values) {
-		for (const token of value
-			.split(',')
-			.map((part) => part.trim())
-			.filter(Boolean)) {
-			seen.add(token);
-		}
-	}
-
-	return Array.from(seen).join(',');
-}
-
-/**
- * Builds a scripts-injector map config from resolved lazy script groups.
- *
- * @param lazyGroups Lazy script groups resolved during dependency processing.
- * @returns Injector map config keyed by lazy trigger.
- */
-function buildInjectorMap(lazyGroups: ResolvedLazyScriptGroup[]): InjectorMapConfig {
-	const map: InjectorMapConfig = {};
-
-	for (const group of lazyGroups) {
-		const scripts = normalizeScripts(group.scripts);
-		const lazy = group.lazy;
-
-		if ('on:idle' in lazy) {
-			map['on:idle'] = {
-				scripts: [...(map['on:idle']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		if ('on:interaction' in lazy) {
-			const currentValue = map['on:interaction']?.value;
-			const nextValue = lazy['on:interaction'];
-
-			map['on:interaction'] = {
-				value: typeof currentValue === 'string' ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
-				scripts: [...(map['on:interaction']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		if ('on:visible' in lazy) {
-			const currentValue = map['on:visible']?.value;
-			const currentThreshold = typeof currentValue === 'string' ? currentValue : undefined;
-			const nextValue = lazy['on:visible'];
-
-			map['on:visible'] = {
-				...(nextValue === true
-					? currentThreshold
-						? { value: currentThreshold }
-						: {}
-					: { value: String(nextValue) }),
-				scripts: [...(map['on:visible']?.scripts ?? []), ...scripts],
-			};
-			continue;
-		}
-
-		throw new Error(
-			`Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`,
-		);
-	}
-
-	for (const key of Object.keys(map)) {
-		const scripts = map[key]?.scripts;
-		if (scripts) {
-			map[key] = {
-				...map[key],
-				scripts: Array.from(new Set(scripts)),
-			};
-		}
-	}
-
-	return map;
-}
-
-/**
- * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
- *
- * @param lazyGroups Lazy script groups resolved during dependency processing.
- * @returns Escaped JSON string safe for inline script embedding.
- */
-export function buildInjectorMapScript(lazyGroups: ResolvedLazyScriptGroup[]): string {
-	const map = buildInjectorMap(lazyGroups);
-	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
-}

package/src/eco/module-dependencies.ts

@@ -1,75 +0,0 @@
-export type ModuleDependencyDeclaration = {
-	from: string;
-	imports?: string[];
-};
-
-function normalizeImports(imports: string[] | undefined): string[] | undefined {
-	if (!imports || imports.length === 0) {
-		return undefined;
-	}
-
-	const normalized = Array.from(new Set(imports.map((entry) => entry.trim()).filter((entry) => entry.length > 0)));
-
-	return normalized.length > 0 ? normalized : undefined;
-}
-
-/**
- * Parses a module grammar declaration into normalized object form.
- *
- * Supported input examples:
- * - `react-aria-components`
- * - `react-aria-components{Table,Select}`
- */
-export function parseModuleDeclaration(value: string): ModuleDependencyDeclaration {
-	const source = value.trim();
-	if (source.length === 0) {
-		throw new Error('Module declaration cannot be empty');
-	}
-
-	const openBraceIndex = source.indexOf('{');
-	if (openBraceIndex < 0) {
-		return { from: source };
-	}
-
-	const closeBraceIndex = source.lastIndexOf('}');
-	if (closeBraceIndex !== source.length - 1 || closeBraceIndex <= openBraceIndex) {
-		throw new Error(`Invalid module declaration '${value}'`);
-	}
-
-	const from = source.slice(0, openBraceIndex).trim();
-	if (from.length === 0) {
-		throw new Error(`Invalid module declaration '${value}'`);
-	}
-
-	const importsSlice = source.slice(openBraceIndex + 1, closeBraceIndex);
-	const imports = normalizeImports(importsSlice.split(','));
-
-	return {
-		from,
-		imports,
-	};
-}
-
-/**
- * Normalizes and deduplicates module declarations from `modules`.
- *
- * Returns canonical object declarations suitable for downstream bundling logic.
- */
-export function normalizeModuleDeclarations(modules?: string[]): ModuleDependencyDeclaration[] {
-	const declarations = modules ?? [];
-
-	const output: ModuleDependencyDeclaration[] = [];
-	const seen = new Set<string>();
-
-	for (const declaration of declarations) {
-		const normalized = parseModuleDeclaration(declaration);
-		const key = `${normalized.from}::${(normalized.imports ?? []).join(',')}`;
-
-		if (!seen.has(key)) {
-			seen.add(key);
-			output.push(normalized);
-		}
-	}
-
-	return output;
-}

package/src/errors/http-error.ts

@@ -1,72 +0,0 @@
-export interface HttpErrorDetails {
-	[key: string]: unknown;
-}
-
-export interface HttpErrorJson {
-	error: string;
-	status: number;
-	details?: HttpErrorDetails;
-}
-
-/**
- * HTTP error class for structured error handling in route handlers.
- * Provides static factory methods for common HTTP error responses.
- */
-export class HttpError extends Error {
-	readonly status: number;
-	readonly details?: HttpErrorDetails;
-
-	constructor(status: number, message: string, details?: HttpErrorDetails) {
-		super(message);
-		this.name = 'HttpError';
-		this.status = status;
-		this.details = details;
-	}
-
-	/**
-	 * Serialize error to JSON for API responses.
-	 */
-	toJSON(): HttpErrorJson {
-		const json: HttpErrorJson = {
-			error: this.message,
-			status: this.status,
-		};
-
-		if (this.details) {
-			json.details = this.details;
-		}
-
-		return json;
-	}
-
-	/**
-	 * Create a Response object from this error.
-	 */
-	toResponse(): Response {
-		return Response.json(this.toJSON(), { status: this.status });
-	}
-
-	static BadRequest(message = 'Bad Request', details?: HttpErrorDetails): HttpError {
-		return new HttpError(400, message, details);
-	}
-
-	static Unauthorized(message = 'Unauthorized'): HttpError {
-		return new HttpError(401, message);
-	}
-
-	static Forbidden(message = 'Forbidden'): HttpError {
-		return new HttpError(403, message);
-	}
-
-	static NotFound(message = 'Not Found'): HttpError {
-		return new HttpError(404, message);
-	}
-
-	static Conflict(message = 'Conflict', details?: HttpErrorDetails): HttpError {
-		return new HttpError(409, message, details);
-	}
-
-	static InternalServerError(message = 'Internal Server Error'): HttpError {
-		return new HttpError(500, message);
-	}
-}

package/src/errors/index.ts

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

package/src/errors/locals-access-error.ts

@@ -1,7 +0,0 @@
-export class LocalsAccessError extends Error {
-	override name = 'LocalsAccessError';
-
-	constructor(message: string) {
-		super(message);
-	}
-}

package/src/global/app-logger.ts

@@ -1,4 +0,0 @@
-import { Logger } from '@ecopages/logger';
-
-const debug = process.env.ECOPAGES_LOGGER_DEBUG === 'true';
-export const appLogger = new Logger('[@ecopages/core]', { debug });

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

@@ -1,152 +0,0 @@
-/**
- * Ecopages HMR Runtime
- * Injected into the browser to handle Hot Module Replacement updates.
- */
-
-import { getEcoNavigationRuntime } from '../../router/client/navigation-coordinator.ts';
-
-interface HMRPayload {
-	type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
-	path?: string;
-	message?: string;
-	timestamp?: number;
-}
-
-(function () {
-	const WS_URL = 'ws://' + location.host + '/_hmr';
-	let socket: WebSocket;
-	let reconnectAttempts = 0;
-
-	function connect() {
-		socket = new WebSocket(WS_URL);
-
-		socket.addEventListener('open', () => {
-			console.log('[ecopages] HMR Connected');
-			reconnectAttempts = 0;
-		});
-
-		socket.addEventListener('message', async (event) => {
-			try {
-				const payload: HMRPayload = JSON.parse(event.data);
-				handleMessage(payload);
-			} catch (e) {
-				console.error('[ecopages] Invalid HMR message:', e);
-			}
-		});
-
-		socket.addEventListener('close', () => {
-			if (reconnectAttempts < 10) {
-				setTimeout(connect, 1000 * 2 ** reconnectAttempts);
-				reconnectAttempts++;
-			}
-		});
-	}
-
-	async function handleMessage(payload: HMRPayload) {
-		const navigationRuntime = getEcoNavigationRuntime(window);
-
-		switch (payload.type) {
-			case 'reload':
-				await waitForNavigationToSettle(navigationRuntime);
-				location.reload();
-				break;
-			case 'layout-update': {
-				await waitForNavigationToSettle(navigationRuntime);
-				if (await navigationRuntime.reloadCurrentPage({ clearCache: true })) {
-				} else {
-					location.reload();
-				}
-				break;
-			}
-			case 'error':
-				console.error('[ecopages] HMR Error:', payload.message);
-				break;
-			case 'update':
-				if (payload.path) {
-					await applyUpdate(payload.path, payload.timestamp);
-				}
-				break;
-			case 'css-update':
-				if (payload.path) {
-					refreshStylesheet(payload.path);
-				}
-				break;
-		}
-	}
-
-	/**
-	 * Applies a module update by calling registered HMR handlers or re-importing the module.
-	 * @param path - The module path to update
-	 * @param timestamp - Optional timestamp for cache busting
-	 */
-	async function applyUpdate(path: string, timestamp?: number) {
-		try {
-			const url = path + '?t=' + (timestamp || Date.now());
-			const handlers = window.__ECO_PAGES__?.hmrHandlers;
-			const navigationRuntime = getEcoNavigationRuntime(window);
-			await waitForNavigationToSettle(navigationRuntime);
-
-			if (handlers?.[path]) {
-				await handlers[path](url);
-				return;
-			}
-
-			await import(url);
-
-			// If we're inside the EcoRouter, we need to trigger a router navigation to render the new component.
-			// Passing clearCache: false preserves the persisted layout cache.
-			if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
-			}
-		} catch (e) {
-			console.error('[ecopages] Failed to apply HMR update:', e);
-		}
-	}
-
-	async function waitForNavigationToSettle(navigationRuntime: ReturnType<typeof getEcoNavigationRuntime>) {
-		if (!navigationRuntime.hasPendingNavigationTransaction()) {
-			return;
-		}
-
-		await new Promise<void>((resolve) => {
-			const startedAt = performance.now();
-			const timeoutMs = 2000;
-
-			const poll = () => {
-				if (!navigationRuntime.hasPendingNavigationTransaction()) {
-					resolve();
-					return;
-				}
-
-				if (performance.now() - startedAt >= timeoutMs) {
-					resolve();
-					return;
-				}
-
-				requestAnimationFrame(poll);
-			};
-
-			requestAnimationFrame(poll);
-		});
-	}
-
-	/**
-	 * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
-	 * This causes the browser to re-fetch the stylesheet without a full page reload.
-	 */
-	function refreshStylesheet(path: string) {
-		const filename = path.split('/').pop() || '';
-		const links = document.querySelectorAll('link[rel="stylesheet"]');
-
-		links.forEach((link) => {
-			const href = (link as HTMLLinkElement).href;
-			if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, '/assets/'))) {
-				const url = new URL(href, location.origin);
-				url.searchParams.set('t', Date.now().toString());
-				(link as HTMLLinkElement).href = url.toString();
-				console.log('[ecopages] CSS updated:', filename);
-			}
-		});
-	}
-
-	connect();
-})();

package/src/hmr/hmr-strategy.ts

@@ -1,172 +0,0 @@
-import type { ClientBridgeEvent } from '../public-types';
-
-/**
- * HMR Strategy Pattern
- *
- * This module defines the base classes and types for Hot Module Replacement strategies.
- * Each strategy handles a specific type of file change and determines how to process it.
- *
- * @module
- * @example
- * ```typescript
- * class CustomHmrStrategy extends HmrStrategy {
- *   readonly type = HmrStrategyType.INTEGRATION;
- *
- *   matches(filePath: string): boolean {
- *     return filePath.endsWith('.custom');
- *   }
- *
- *   async process(filePath: string): Promise<HmrAction> {
- *     return {
- *       type: 'broadcast',
- *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
- *     };
- *   }
- * }
-
- * Defines the category of an HMR strategy, which determines its execution priority.
- * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
- *
- * @remarks
- * The numeric values represent base priorities. Strategies can fine-tune their priority
- * using the `priorityOffset` property.
- */
-export enum HmrStrategyType {
-	/**
-	 * Integration-specific strategies (React, Lit, etc.)
-	 * Highest priority to allow framework-specific HMR handling.
-	 */
-	INTEGRATION = 100,
-
-	/**
-	 * Asset processing strategies (CSS, images, etc.)
-	 * High priority for specialized asset handling.
-	 */
-	ASSET = 50,
-
-	/**
-	 * Generic script bundling strategies (JS/TS)
-	 * Medium priority for standard script processing.
-	 */
-	SCRIPT = 25,
-
-	/**
-	 * Fallback strategy for unhandled file types.
-	 * Lowest priority, triggers full page reload.
-	 */
-	FALLBACK = 0,
-}
-
-/**
- * Represents an action to be taken after processing a file change.
- */
-export interface HmrAction {
-	/**
-	 * Whether to broadcast an HMR event to connected clients.
-	 */
-	type: 'broadcast' | 'none';
-
-	/**
-	 * The HMR events to broadcast, if type is 'broadcast'.
-	 * capable of broadcasting multiple events at once.
-	 */
-	events?: ClientBridgeEvent[];
-}
-
-/**
- * Base class for HMR strategies.
- *
- * Each strategy handles a specific type of file change and determines how to process it.
- * Strategies are selected based on their priority (higher values are evaluated first) and
- * whether they match the changed file path.
- *
- * @remarks
- * Strategies should be stateless and idempotent. The same file change should always
- * produce the same result when processed by the same strategy.
- *
- * @example
- * ```typescript
- * class MyAssetStrategy extends HmrStrategy {
- *   readonly type = HmrStrategyType.ASSET;
- *   readonly priorityOffset = 5;
- *
- *   matches(filePath: string): boolean {
- *     return /\.(png|jpg|svg)$/.test(filePath);
- *   }
- *
- *   async process(filePath: string): Promise<HmrAction> {
- *     await this.optimizeImage(filePath);
- *     return {
- *       type: 'broadcast',
- *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
- *     };
- *   }
- * }
- * ```
- */
-export abstract class HmrStrategy {
-	/**
-	 * The category of this strategy, determining its base priority.
-	 */
-	abstract readonly type: HmrStrategyType;
-
-	/**
-	 * Optional offset to fine-tune priority within the same category.
-	 * Useful when multiple strategies share the same type.
-	 *
-	 * @defaultValue 0
-	 */
-	readonly priorityOffset: number = 0;
-
-	/**
-	 * Computed priority for strategy selection.
-	 * Higher values are evaluated first.
-	 *
-	 * @returns The sum of the strategy type and priority offset
-	 */
-	get priority(): number {
-		return this.type + this.priorityOffset;
-	}
-
-	/**
-	 * Determines if this strategy can handle the given file path.
-	 *
-	 * @param filePath - Absolute path to the changed file
-	 * @returns True if this strategy should process the file
-	 *
-	 * @example
-	 * ```typescript
-	 * matches(filePath: string): boolean {
-	 *   return filePath.endsWith('.css');
-	 * }
-	 * ```
-	 */
-	abstract matches(filePath: string): boolean;
-
-	/**
-	 * Processes a file change and returns the action to take.
-	 *
-	 * This method may perform side effects such as:
-	 * - Rebuilding files
-	 * - Writing to disk
-	 * - Transforming code
-	 * - Updating caches
-	 *
-	 * @param filePath - Absolute path to the changed file
-	 * @returns Action to take (broadcast event or none)
-	 *
-	 * @example
-	 * ```typescript
-	 * async process(filePath: string): Promise<HmrAction> {
-	 *   const processed = await this.transform(filePath);
-	 *   await Bun.write(outputPath, processed);
-	 *
-	 *   return {
-	 *     type: 'broadcast',
-	 *     events: [{ type: 'update', path: outputPath, timestamp: Date.now() }]
-	 *   };
-	 * }
-	 * ```
-	 */
-	abstract process(filePath: string): Promise<HmrAction>;
-}

package/src/hmr/hmr.postcss.test.e2e.ts

@@ -1,41 +0,0 @@
-import { test, expect } from '@playwright/test';
-import { readFileSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-const FIXTURE_DIR = resolve(process.cwd(), 'packages/core/__fixtures__/app');
-const TEST_CSS_FILE = resolve(FIXTURE_DIR, 'src/pages/postcss-hmr.css');
-
-test.describe('HMR E2E PostCSS', () => {
-	test('should hot-update processor-owned CSS without a full page reload', async ({ page }) => {
-		const originalCss = readFileSync(TEST_CSS_FILE, 'utf-8');
-		const title = page.locator('.postcss-title').first();
-
-		try {
-			await page.goto('/postcss-hmr', { waitUntil: 'networkidle' });
-			await expect(title).toBeVisible();
-
-			const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
-			expect(initialColor).toBeTruthy();
-			await page.evaluate(() => {
-				(window as typeof window & { __postcssReloadProbe?: string }).__postcssReloadProbe = 'before-change';
-			});
-
-			const modifiedCss = originalCss.replace('.postcss-title {', '.postcss-title {\n\tcolor: rgb(255, 0, 0);');
-
-			await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
-
-			await expect
-				.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 10000 })
-				.toBe('rgb(255, 0, 0)');
-
-			await expect(
-				page.evaluate(
-					() => (window as typeof window & { __postcssReloadProbe?: string }).__postcssReloadProbe ?? null,
-				),
-			).resolves.toBe('before-change');
-		} finally {
-			await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
-		}
-	});
-});