@useavalon/avalon 0.1.12 → 0.1.13

package/src/core/modules/framework-module-resolver.ts

@@ -0,0 +1,273 @@
+/**
+ * Framework-aware module resolver for handling framework-specific path transformations
+ * and MIME type resolution during hydration and module serving.
+ */
+
+export interface ModuleResolutionConfig {
+	framework: string;
+	baseUrl: string;
+	extensions: string[];
+	transformPath: (path: string) => string;
+	mimeType: string;
+}
+
+export interface ResolvedModule {
+	originalPath: string;
+	resolvedPath: string;
+	framework: string;
+	shouldTransform: boolean;
+	mimeType: string;
+	url: string;
+}
+
+export interface FrameworkModuleConfig {
+	extensions: string[];
+	hydrationExtension: string;
+	mimeType: string;
+	transformPath: (path: string, mode: 'development' | 'production') => string;
+}
+
+/**
+ * Framework-specific module configurations
+ */
+const FRAMEWORK_MODULE_CONFIGS: Record<string, FrameworkModuleConfig> = {
+	solid: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// For Solid, transform .tsx to .js for hydration
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+	preact: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// For Preact, transform .tsx/.jsx to .js for hydration
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+	vue: {
+		extensions: ['.vue'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Vue components are typically compiled to .js
+			if (path.endsWith('.vue')) {
+				return path.replace(/\.vue$/, '.js');
+			}
+			return path;
+		},
+	},
+	svelte: {
+		extensions: ['.svelte'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Svelte components are compiled to .js
+			if (path.endsWith('.svelte')) {
+				return path.replace(/\.svelte$/, '.js');
+			}
+			return path;
+		},
+	},
+	qwik: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Qwik components are compiled to .js via the Qwik optimizer
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+};
+
+export class FrameworkModuleResolver {
+	private mode: 'development' | 'production';
+	private baseUrl: string;
+
+	constructor(mode: 'development' | 'production' = 'development', baseUrl = '') {
+		this.mode = mode;
+		this.baseUrl = baseUrl;
+	}
+
+	/**
+	 * Resolve a module path for a specific framework
+	 */
+	resolveModule(
+		originalPath: string,
+		framework: string,
+		options: {
+			forHydration?: boolean;
+			baseUrl?: string;
+		} = {}
+	): ResolvedModule {
+		const config = FRAMEWORK_MODULE_CONFIGS[framework];
+		if (!config) {
+			throw new Error(`Unknown framework: ${framework}`);
+		}
+
+		const { forHydration = false, baseUrl = this.baseUrl } = options;
+
+		let resolvedPath = originalPath;
+		let shouldTransform = false;
+		let mimeType = this.getMimeType(originalPath);
+
+		// Apply framework-specific path transformation for hydration
+		if (forHydration) {
+			const transformedPath = config.transformPath(originalPath, this.mode);
+			if (transformedPath !== originalPath) {
+				resolvedPath = transformedPath;
+				shouldTransform = true;
+				mimeType = config.mimeType;
+			}
+		}
+
+		// Generate the full URL
+		const url = this.generateModuleUrl(resolvedPath, baseUrl);
+
+		return {
+			originalPath,
+			resolvedPath,
+			framework,
+			shouldTransform,
+			mimeType,
+			url,
+		};
+	}
+
+	/**
+	 * Check if a path needs transformation for the given framework
+	 */
+	needsTransformation(path: string, framework: string): boolean {
+		const config = FRAMEWORK_MODULE_CONFIGS[framework];
+		if (!config) {
+			return false;
+		}
+
+		const transformedPath = config.transformPath(path, this.mode);
+		return transformedPath !== path;
+	}
+
+	/**
+	 * Get the appropriate MIME type for a file path
+	 */
+	getMimeType(path: string): string {
+		const ext = this.getFileExtension(path);
+
+		switch (ext) {
+			case '.js':
+			case '.mjs':
+				return 'application/javascript';
+			case '.ts':
+			case '.tsx':
+			case '.jsx':
+				return 'application/javascript'; // These are typically compiled to JS
+			case '.css':
+				return 'text/css';
+			case '.json':
+				return 'application/json';
+			case '.vue':
+			case '.svelte':
+				return 'application/javascript'; // Compiled components
+			default:
+				return 'text/plain';
+		}
+	}
+
+	/**
+	 * Generate a module URL for the given path
+	 */
+	generateModuleUrl(path: string, baseUrl = this.baseUrl): string {
+		// Ensure path starts with /
+		const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+
+		if (baseUrl) {
+			return `${baseUrl.replace(/\/$/, '')}${normalizedPath}`;
+		}
+
+		return normalizedPath;
+	}
+
+	/**
+	 * Get supported frameworks
+	 */
+	getSupportedFrameworks(): string[] {
+		return Object.keys(FRAMEWORK_MODULE_CONFIGS);
+	}
+
+	/**
+	 * Get framework configuration
+	 */
+	getFrameworkConfig(framework: string): FrameworkModuleConfig | undefined {
+		return FRAMEWORK_MODULE_CONFIGS[framework];
+	}
+
+	/**
+	 * Check if a framework is supported
+	 */
+	isFrameworkSupported(framework: string): boolean {
+		return framework in FRAMEWORK_MODULE_CONFIGS;
+	}
+
+	/**
+	 * Get file extension from path
+	 */
+	private getFileExtension(path: string): string {
+		const lastDot = path.lastIndexOf('.');
+		return lastDot === -1 ? '' : path.substring(lastDot);
+	}
+
+	/**
+	 * Set the resolver mode (development/production)
+	 */
+	setMode(mode: 'development' | 'production'): void {
+		this.mode = mode;
+	}
+
+	/**
+	 * Get current mode
+	 */
+	getMode(): 'development' | 'production' {
+		return this.mode;
+	}
+
+	/**
+	 * Set base URL for module resolution
+	 */
+	setBaseUrl(baseUrl: string): void {
+		this.baseUrl = baseUrl;
+	}
+
+	/**
+	 * Get current base URL
+	 */
+	getBaseUrl(): string {
+		return this.baseUrl;
+	}
+}
+
+/**
+ * Default instance for common usage
+ */
+export const frameworkModuleResolver = new FrameworkModuleResolver();

package/src/islands/component-analysis.ts

@@ -0,0 +1,213 @@
+import type { JSX } from 'preact';
+import {
+	analyzeComponentContent,
+	type AnalyzerOptions,
+	type AnalysisReport,
+} from '../core/components/component-analyzer.ts';
+import { resolveIslandPath } from './framework-detection.ts';
+import type { IslandProps } from './types.ts';
+import { getCachedAnalysis, setCachedAnalysis, getCachedPath, setCachedPath } from './render-cache.ts';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Check if we're in development mode
+ */
+function isDev(): boolean {
+	try {
+		return process.env.NODE_ENV !== 'production';
+	} catch {
+		return true; // Default to dev mode if we can't check
+	}
+}
+
+/**
+ * Log cache hit/miss in dev mode
+ */
+function logCacheEvent(_type: 'hit' | 'miss', _cacheType: string, _src: string): void {
+	// Silenced — set AVALON_VERBOSE=1 to enable
+}
+
+/**
+ * Get essential path variations for a component
+ * Reduced from 22 variations to essential ones for better performance
+ */
+function getEssentialPathVariations(src: string, resolvedSrc: string): string[] {
+	const baseName =
+		src
+			.split('/')
+			.pop()
+			?.replace(/\.(tsx|jsx|vue|svelte|ts|js)$/, '') || '';
+
+	// Get the original file extension
+	const originalExt = src.split('.').pop() || 'tsx';
+
+	// Essential path variations - prioritized by likelihood
+	return [
+		// Direct paths first (most likely to succeed)
+		resolvedSrc.startsWith('/') ? resolvedSrc.substring(1) : resolvedSrc,
+		src.startsWith('/') ? src.substring(1) : src,
+		// Standard island locations
+		`src/islands/${baseName}.${originalExt}`,
+		`src/islands/${baseName}.tsx`,
+		`islands/${baseName}.${originalExt}`,
+		`islands/${baseName}.tsx`,
+		// Framework-specific extensions (only for common frameworks)
+		`src/islands/${baseName}.svelte`,
+		`src/islands/${baseName}.vue`,
+		`src/islands/${baseName}.solid.tsx`,
+	];
+}
+
+/**
+ * Try to read a file asynchronously, returning null if not found
+ */
+async function tryReadFile(path: string): Promise<string | null> {
+	try {
+		return await readFile(path, 'utf-8');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Analyze component file for rendering strategy
+ *
+ * Attempts to read the component file from various path variations and
+ * analyzes its content to determine the optimal rendering strategy.
+ * Uses caching to avoid repeated file I/O and analysis for the same components.
+ *
+ * @param src - The source path to the component
+ * @param options - Analyzer options for customizing the analysis
+ * @returns Analysis result with rendering strategy decision
+ * @throws Error if component file cannot be found
+ */
+export async function analyzeComponentFile(src: string, options: AnalyzerOptions = {}): Promise<AnalysisReport> {
+	// Check analysis cache first
+	const cachedAnalysis = getCachedAnalysis(src);
+	if (cachedAnalysis) {
+		logCacheEvent('hit', 'analysis', src);
+		return cachedAnalysis;
+	}
+	logCacheEvent('miss', 'analysis', src);
+
+	// Check if we have a cached resolved path
+	let resolvedSrc = getCachedPath(src);
+	if (resolvedSrc) {
+		logCacheEvent('hit', 'path', src);
+	} else {
+		logCacheEvent('miss', 'path', src);
+		resolvedSrc = await resolveIslandPath(src);
+	}
+
+	// Get essential path variations (reduced from 22 to ~9)
+	const pathVariations = getEssentialPathVariations(src, resolvedSrc);
+
+	// Try each path variation
+	for (const pathVariation of pathVariations) {
+		const content = await tryReadFile(pathVariation);
+		if (content !== null) {
+			// Cache the resolved path for future lookups
+			setCachedPath(src, pathVariation);
+
+			// Analyze the component content
+			const result = analyzeComponentContent(pathVariation, content, options);
+
+			// Cache the analysis result
+			setCachedAnalysis(src, result);
+
+			return result;
+		}
+	}
+
+	throw new Error(`Component file not found: ${src}`);
+}
+
+/**
+ * Render component with SSR-only strategy (no hydration)
+ *
+ * Renders a component server-side without adding client-side hydration.
+ * This is useful for static components that don't require interactivity.
+ *
+ * @param params - Rendering parameters
+ * @param params.src - Component source path
+ * @param params.condition - Island hydration condition
+ * @param params.props - Props to pass to the component
+ * @param params.framework - Optional explicit framework (if not provided, will be detected)
+ * @param params.renderOptions - Additional render options
+ * @returns Island component with SSR-only rendering
+ * @throws Error if SSR rendering fails
+ */
+export async function renderComponentSSROnly({
+	src,
+	condition,
+	props,
+	framework: explicitFramework,
+	renderOptions,
+}: {
+	src: string;
+	condition: IslandProps['condition'];
+	props: Record<string, unknown>;
+	framework?: string;
+	renderOptions: AnalyzerOptions;
+}) {
+	try {
+		// Import Island component dynamically to avoid circular dependencies
+		const { default: Island } = await import('./island.tsx');
+
+		// Import integration loader to load the appropriate framework integration
+		const { loadIntegration } = await import('./integration-loader.ts');
+		const { detectFramework } = await import('./framework-detection.ts');
+
+		// Use explicit framework if provided, otherwise detect it
+		let framework: string;
+		if (explicitFramework) {
+			framework = explicitFramework;
+		} else if (src.endsWith('.vue')) {
+			framework = 'vue';
+		} else if (src.endsWith('.svelte')) {
+			framework = 'svelte';
+		} else if (src.endsWith('.tsx') || src.endsWith('.jsx') || src.endsWith('.ts') || src.endsWith('.js')) {
+			framework = await detectFramework(src);
+		} else {
+			framework = 'preact'; // Default fallback
+		}
+
+		// Load the appropriate integration
+		const integration = await loadIntegration(framework);
+
+		// Get Vite server reference for dev mode
+		const viteServer = globalThis.__viteDevServer;
+		const isDev = process.env.NODE_ENV !== 'production';
+
+		// Render the component using the integration
+		const renderResult = await integration.render({
+			component: null, // Integration will load the component from src
+			props,
+			src,
+			condition,
+			ssrOnly: true,
+			viteServer,
+			isDev,
+		});
+
+		// Return Island component with the rendered HTML as children
+		// This ensures the HTML is properly wrapped in <avalon-island> with ssrOnly attributes
+		return Island({
+			src,
+			condition,
+			props,
+			children: renderResult.html, // Pass rendered HTML as children
+			ssr: true,
+			framework: framework as 'solid' | 'vue' | 'preact' | 'react' | 'svelte' | 'lit' | 'qwik',
+			ssrOnly: true,
+			renderOptions,
+			hydrationData: undefined, // No hydration data for SSR-only components
+		});
+	} catch (error) {
+		// Only log errors in development
+		if (process.env.NODE_ENV !== 'production') {
+			console.error(`SSR-only rendering failed for ${src}:`, error);
+		}
+		throw error;
+	}
+}