@useavalon/core 0.1.1 → 0.1.3

package/base-integration.ts

@@ -1,111 +1,111 @@
-/**
- * Abstract base class for framework integrations.
- * Provides common functionality and enforces the Integration interface.
- */
-
-import type {
-  Integration,
-  IntegrationConfig,
-  RenderParams,
-  RenderResult,
-} from "./types.ts";
-import type { Plugin } from "vite";
-
-/**
- * Abstract base class that integrations can extend to inherit common functionality
- */
-export abstract class BaseIntegration implements Integration {
-  abstract name: string;
-  abstract version: string;
-
-  /**
-   * Render a component to HTML (must be implemented by subclass)
-   */
-  abstract render(params: RenderParams): Promise<RenderResult>;
-
-  /**
-   * Get hydration script (must be implemented by subclass)
-   */
-  abstract getHydrationScript(): string;
-
-  /**
-   * Get integration configuration (must be implemented by subclass)
-   */
-  abstract config(): IntegrationConfig;
-
-  /**
-   * Optional Vite plugin configuration
-   * Subclasses can override this to provide build-time processing
-   */
-  vitePlugin?(): Promise<Plugin | Plugin[]> {
-    return Promise.resolve(undefined as unknown as Plugin);
-  }
-
-  /**
-   * Validate render parameters
-   * @param params - Parameters to validate
-   * @throws Error if parameters are invalid
-   */
-  protected validateRenderParams(params: RenderParams): void {
-    if (!params.src) {
-      throw new Error(
-        `[${this.name}] Missing required parameter: src`,
-      );
-    }
-
-    if (typeof params.props !== "object" || params.props === null) {
-      throw new Error(
-        `[${this.name}] Invalid props: must be an object`,
-      );
-    }
-  }
-
-  /**
-   * Create a render error with integration context
-   * @param message - Error message
-   * @param cause - Original error
-   * @returns Error with context
-   */
-  protected createRenderError(message: string, cause?: unknown): Error {
-    const error = new Error(
-      `[${this.name}] ${message}`,
-      cause ? { cause } : undefined,
-    );
-    return error;
-  }
-
-  /**
-   * Log a warning message with integration context
-   * @param message - Warning message
-   */
-  protected warn(message: string): void {
-    console.warn(`[${this.name}] ${message}`);
-  }
-
-  /**
-   * Log an error message with integration context
-   * @param message - Error message
-   * @param error - Optional error object
-   */
-  protected error(message: string, error?: unknown): void {
-    console.error(`[${this.name}] ${message}`, error || "");
-  }
-
-  /**
-   * Check if running in development mode
-   * @param params - Render parameters
-   * @returns True if in development mode
-   */
-  protected isDevelopment(params: RenderParams): boolean {
-    return params.isDev ?? process.env.NODE_ENV !== "production";
-  }
-
-  /**
-   * Get the Vite dev server if available
-   * @param params - Render parameters
-   * @returns Vite dev server or undefined
-   */
-  protected getViteServer(params: RenderParams): unknown {
-    return params.viteServer ?? (globalThis as Record<string, unknown>).__viteDevServer;
-  }
-}
+/**
+ * Abstract base class for framework integrations.
+ * Provides common functionality and enforces the Integration interface.
+ */
+
+import type {
+  Integration,
+  IntegrationConfig,
+  RenderParams,
+  RenderResult,
+} from "./types.ts";
+import type { Plugin } from "vite";
+
+/**
+ * Abstract base class that integrations can extend to inherit common functionality
+ */
+export abstract class BaseIntegration implements Integration {
+  abstract name: string;
+  abstract version: string;
+
+  /**
+   * Render a component to HTML (must be implemented by subclass)
+   */
+  abstract render(params: RenderParams): Promise<RenderResult>;
+
+  /**
+   * Get hydration script (must be implemented by subclass)
+   */
+  abstract getHydrationScript(): string;
+
+  /**
+   * Get integration configuration (must be implemented by subclass)
+   */
+  abstract config(): IntegrationConfig;
+
+  /**
+   * Optional Vite plugin configuration
+   * Subclasses can override this to provide build-time processing
+   */
+  vitePlugin?(): Promise<Plugin | Plugin[]> {
+    return Promise.resolve(undefined as unknown as Plugin);
+  }
+
+  /**
+   * Validate render parameters
+   * @param params - Parameters to validate
+   * @throws Error if parameters are invalid
+   */
+  protected validateRenderParams(params: RenderParams): void {
+    if (!params.src) {
+      throw new Error(
+        `[${this.name}] Missing required parameter: src`,
+      );
+    }
+
+    if (typeof params.props !== "object" || params.props === null) {
+      throw new Error(
+        `[${this.name}] Invalid props: must be an object`,
+      );
+    }
+  }
+
+  /**
+   * Create a render error with integration context
+   * @param message - Error message
+   * @param cause - Original error
+   * @returns Error with context
+   */
+  protected createRenderError(message: string, cause?: unknown): Error {
+    const error = new Error(
+      `[${this.name}] ${message}`,
+      cause ? { cause } : undefined,
+    );
+    return error;
+  }
+
+  /**
+   * Log a warning message with integration context
+   * @param message - Warning message
+   */
+  protected warn(message: string): void {
+    console.warn(`[${this.name}] ${message}`);
+  }
+
+  /**
+   * Log an error message with integration context
+   * @param message - Error message
+   * @param error - Optional error object
+   */
+  protected error(message: string, error?: unknown): void {
+    console.error(`[${this.name}] ${message}`, error || "");
+  }
+
+  /**
+   * Check if running in development mode
+   * @param params - Render parameters
+   * @returns True if in development mode
+   */
+  protected isDevelopment(params: RenderParams): boolean {
+    return params.isDev ?? process.env.NODE_ENV !== "production";
+  }
+
+  /**
+   * Get the Vite dev server if available
+   * @param params - Render parameters
+   * @returns Vite dev server or undefined
+   */
+  protected getViteServer(params: RenderParams): unknown {
+    return params.viteServer ?? (globalThis as Record<string, unknown>).__viteDevServer;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@useavalon/core",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Core types and utilities for Avalon framework integrations",
 	"license": "MIT",
 	"type": "module",
@@ -10,15 +10,24 @@
 		"directory": "packages/integrations/core"
 	},
 	"homepage": "https://useavalon.dev",
-	"keywords": ["avalon", "islands", "framework", "core"],
+	"keywords": [
+		"avalon",
+		"islands",
+		"framework",
+		"core"
+	],
 	"exports": {
 		".": "./types.ts",
 		"./types": "./types.ts",
 		"./utils": "./utils.ts",
 		"./base": "./base-integration.ts"
 	},
-	"files": ["*.ts", "README.md"],
-	"dependencies": {
-		"vite": "8.0.0"
+	"files": [
+		"*.ts",
+		"!vitest.config.ts",
+		"README.md"
+	],
+	"peerDependencies": {
+		"vite": "^8.0.0"
 	}
 }

package/types.ts

@@ -1,156 +1,156 @@
-/**
- * Core types for the Avalon framework integration system.
- * These types define the contract that all framework integrations must implement.
- */
-
-import type { Plugin, ViteDevServer } from 'vite';
-
-/**
- * Hydration condition types that determine when an island should become interactive
- */
-export type HydrationCondition =
-	| 'on:client' // Hydrate immediately on page load
-	| 'on:visible' // Hydrate when island enters viewport
-	| 'on:interaction' // Hydrate on first user interaction
-	| 'on:idle' // Hydrate when browser is idle
-	| `media:${string}`; // Hydrate when media query matches
-
-/**
- * Parameters passed to the integration's render function
- */
-export interface RenderParams {
-	/** The component to render (may be null if integration loads it) */
-	component: unknown;
-	/** Props to pass to the component */
-	props: Record<string, unknown>;
-	/** Source path to the component file */
-	src: string;
-	/** Hydration condition for the island */
-	condition?: HydrationCondition;
-	/** If true, component will not hydrate on client */
-	ssrOnly?: boolean;
-	/** Vite dev server instance (available in development) */
-	viteServer?: ViteDevServer;
-	/** Whether running in development mode */
-	isDev?: boolean;
-}
-
-/**
- * Result returned from the integration's render function
- */
-export interface RenderResult {
-	/** Rendered HTML string */
-	html: string;
-	/** CSS to inject (for frameworks with scoped styles) */
-	css?: string;
-	/** Additional head content (scripts, meta tags, etc.) */
-	head?: string;
-	/** Scope ID for CSS scoping (e.g., Vue scoped styles) */
-	scopeId?: string;
-	/** Data to serialize for client-side hydration */
-	hydrationData?: Record<string, unknown>;
-}
-
-/**
- * Configuration for a framework integration
- */
-export interface IntegrationConfig {
-	/** Unique name of the integration (e.g., "preact", "vue") */
-	name: string;
-	/** File extensions this integration handles */
-	fileExtensions: string[];
-	/** JSX import sources for this framework */
-	jsxImportSources?: string[];
-	/** Patterns to detect if a file uses this framework */
-	detectionPatterns: {
-		/** Regex patterns to match import statements */
-		imports: RegExp[];
-		/** Regex patterns to match code content */
-		content: RegExp[];
-	};
-}
-
-/**
- * Main integration interface that all framework integrations must implement
- */
-export interface Integration {
-	/** Unique name of the integration */
-	name: string;
-	/** Version of the integration package */
-	version: string;
-
-	/**
-	 * Render a component to HTML on the server
-	 * @param params - Rendering parameters
-	 * @returns Promise resolving to render result
-	 */
-	render(params: RenderParams): Promise<RenderResult>;
-
-	/**
-	 * Get the hydration script for client-side initialization
-	 * @returns JavaScript code as a string
-	 */
-	getHydrationScript(): string;
-
-	/**
-	 * Get the integration configuration
-	 * @returns Integration configuration object
-	 */
-	config(): IntegrationConfig;
-
-	/**
-	 * Optional: Provide Vite plugins required for this framework's build-time processing.
-	 *
-	 * Each integration encapsulates its own Vite plugin configuration, eliminating
-	 * the need for manual framework plugin setup in the user's vite.config.ts.
-	 *
-	 * **Plugin Ordering Requirements:**
-	 * - Lit integration plugins MUST be placed first (DOM shim requirement)
-	 * - MDX plugins should come after Lit but before other framework plugins
-	 * - Framework-specific plugins (React, Vue, Svelte, etc.) come last
-	 *
-	 * The Avalon plugin handles ordering automatically when collecting plugins
-	 * from all activated integrations.
-	 *
-	 * @returns Promise resolving to a single Vite plugin or array of plugins
-	 *
-	 * @example
-	 * ```typescript
-	 * async vitePlugin(): Promise<Plugin | Plugin[]> {
-	 *   const { default: vue } = await import('@vitejs/plugin-vue');
-	 *   return vue({
-	 *     template: {
-	 *       compilerOptions: {
-	 *         isCustomElement: tag => tag === 'avalon-island',
-	 *       },
-	 *     },
-	 *   });
-	 * }
-	 * ```
-	 */
-	vitePlugin?(): Promise<Plugin | Plugin[]>;
-}
-
-/**
- * Context available during component loading
- */
-export interface LoadContext {
-	/** Whether running in development mode */
-	isDev: boolean;
-	/** Vite dev server instance (available in development) */
-	viteServer?: ViteDevServer;
-	/** Path to build output directory (production) */
-	buildOutput?: string;
-}
-
-/**
- * Options for component loading
- */
-export interface ComponentLoadOptions {
-	/** Source path to the component */
-	src: string;
-	/** Load context */
-	context: LoadContext;
-	/** Whether to load for SSR or client */
-	target?: 'ssr' | 'client';
-}
+/**
+ * Core types for the Avalon framework integration system.
+ * These types define the contract that all framework integrations must implement.
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+
+/**
+ * Hydration condition types that determine when an island should become interactive
+ */
+export type HydrationCondition =
+	| 'on:client' // Hydrate immediately on page load
+	| 'on:visible' // Hydrate when island enters viewport
+	| 'on:interaction' // Hydrate on first user interaction
+	| 'on:idle' // Hydrate when browser is idle
+	| `media:${string}`; // Hydrate when media query matches
+
+/**
+ * Parameters passed to the integration's render function
+ */
+export interface RenderParams {
+	/** The component to render (may be null if integration loads it) */
+	component: unknown;
+	/** Props to pass to the component */
+	props: Record<string, unknown>;
+	/** Source path to the component file */
+	src: string;
+	/** Hydration condition for the island */
+	condition?: HydrationCondition;
+	/** If true, component will not hydrate on client */
+	ssrOnly?: boolean;
+	/** Vite dev server instance (available in development) */
+	viteServer?: ViteDevServer;
+	/** Whether running in development mode */
+	isDev?: boolean;
+}
+
+/**
+ * Result returned from the integration's render function
+ */
+export interface RenderResult {
+	/** Rendered HTML string */
+	html: string;
+	/** CSS to inject (for frameworks with scoped styles) */
+	css?: string;
+	/** Additional head content (scripts, meta tags, etc.) */
+	head?: string;
+	/** Scope ID for CSS scoping (e.g., Vue scoped styles) */
+	scopeId?: string;
+	/** Data to serialize for client-side hydration */
+	hydrationData?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for a framework integration
+ */
+export interface IntegrationConfig {
+	/** Unique name of the integration (e.g., "preact", "vue") */
+	name: string;
+	/** File extensions this integration handles */
+	fileExtensions: string[];
+	/** JSX import sources for this framework */
+	jsxImportSources?: string[];
+	/** Patterns to detect if a file uses this framework */
+	detectionPatterns: {
+		/** Regex patterns to match import statements */
+		imports: RegExp[];
+		/** Regex patterns to match code content */
+		content: RegExp[];
+	};
+}
+
+/**
+ * Main integration interface that all framework integrations must implement
+ */
+export interface Integration {
+	/** Unique name of the integration */
+	name: string;
+	/** Version of the integration package */
+	version: string;
+
+	/**
+	 * Render a component to HTML on the server
+	 * @param params - Rendering parameters
+	 * @returns Promise resolving to render result
+	 */
+	render(params: RenderParams): Promise<RenderResult>;
+
+	/**
+	 * Get the hydration script for client-side initialization
+	 * @returns JavaScript code as a string
+	 */
+	getHydrationScript(): string;
+
+	/**
+	 * Get the integration configuration
+	 * @returns Integration configuration object
+	 */
+	config(): IntegrationConfig;
+
+	/**
+	 * Optional: Provide Vite plugins required for this framework's build-time processing.
+	 *
+	 * Each integration encapsulates its own Vite plugin configuration, eliminating
+	 * the need for manual framework plugin setup in the user's vite.config.ts.
+	 *
+	 * **Plugin Ordering Requirements:**
+	 * - Lit integration plugins MUST be placed first (DOM shim requirement)
+	 * - MDX plugins should come after Lit but before other framework plugins
+	 * - Framework-specific plugins (React, Vue, Svelte, etc.) come last
+	 *
+	 * The Avalon plugin handles ordering automatically when collecting plugins
+	 * from all activated integrations.
+	 *
+	 * @returns Promise resolving to a single Vite plugin or array of plugins
+	 *
+	 * @example
+	 * ```typescript
+	 * async vitePlugin(): Promise<Plugin | Plugin[]> {
+	 *   const { default: vue } = await import('@vitejs/plugin-vue');
+	 *   return vue({
+	 *     template: {
+	 *       compilerOptions: {
+	 *         isCustomElement: tag => tag === 'avalon-island',
+	 *       },
+	 *     },
+	 *   });
+	 * }
+	 * ```
+	 */
+	vitePlugin?(): Promise<Plugin | Plugin[]>;
+}
+
+/**
+ * Context available during component loading
+ */
+export interface LoadContext {
+	/** Whether running in development mode */
+	isDev: boolean;
+	/** Vite dev server instance (available in development) */
+	viteServer?: ViteDevServer;
+	/** Path to build output directory (production) */
+	buildOutput?: string;
+}
+
+/**
+ * Options for component loading
+ */
+export interface ComponentLoadOptions {
+	/** Source path to the component */
+	src: string;
+	/** Load context */
+	context: LoadContext;
+	/** Whether to load for SSR or client */
+	target?: 'ssr' | 'client';
+}

package/utils.ts

@@ -1,234 +1,234 @@
-/**
- * Common utilities for framework integrations.
- * Provides shared functionality for component loading, path resolution, and more.
- */
-
-import type { ComponentLoadOptions, LoadContext } from './types.ts';
-import type { ViteDevServer } from 'vite';
-import { join, resolve } from 'node:path';
-
-/**
- * Load a component module in development or production
- * @param options - Component load options
- * @returns The loaded component module
- */
-export async function loadComponent(options: ComponentLoadOptions) {
-	const { src, context, target = 'ssr' } = options;
-
-	if (context.isDev && context.viteServer) {
-		return await loadComponentDev(src, context.viteServer);
-	}
-
-	return await loadComponentProd(src, context.buildOutput, target);
-}
-
-/**
- * Load a component in development mode using Vite's SSR loader
- * @param src - Source path to component
- * @param viteServer - Vite dev server instance
- * @returns The loaded component module
- */
-async function loadComponentDev(src: string, viteServer: ViteDevServer) {
-	try {
-		const module = await viteServer.ssrLoadModule(src);
-		return module.default || module;
-	} catch (error) {
-		throw new Error(`Failed to load component in development: ${src}`, { cause: error });
-	}
-}
-
-/**
- * Load a component in production mode from build output
- * @param src - Source path to component
- * @param buildOutput - Path to build output directory
- * @param target - Whether loading for SSR or client
- * @returns The loaded component module
- */
-async function loadComponentProd(src: string, buildOutput: string | undefined, target: 'ssr' | 'client') {
-	const outputPath = resolveProductionPath(src, buildOutput, target);
-
-	try {
-		const module = await import(/* @vite-ignore */ toImportSpecifier(outputPath));
-		return module.default || module;
-	} catch (error) {
-		throw new Error(`Failed to load component in production: ${outputPath}`, { cause: error });
-	}
-}
-
-/**
- * Resolve the production build path for a component
- * @param src - Source path to component
- * @param buildOutput - Path to build output directory
- * @param target - Whether loading for SSR or client
- * @returns Resolved path to built component
- */
-export function resolveProductionPath(src: string, buildOutput: string | undefined, target: 'ssr' | 'client') {
-	const base = buildOutput || 'dist';
-	const targetDir = target === 'ssr' ? 'ssr' : 'client';
-
-	// Convert source path to output path
-	// e.g., /islands/Counter.tsx -> /dist/ssr/islands/Counter.js
-	const outputPath = src
-		.replace(/^\//, '') // Remove leading slash
-		.replace(/\.(tsx|jsx|ts|js|vue|svelte)$/, '.js'); // Change extension to .js
-
-	return join(base, targetDir, outputPath);
-}
-
-/**
- * Normalize a component path to be absolute
- * @param src - Source path (may be relative or absolute)
- * @param baseDir - Base directory to resolve relative paths from
- * @returns Absolute path
- */
-export function normalizePath(src: string, baseDir?: string) {
-	if (src.startsWith('/') || src.startsWith('file://')) {
-		return src;
-	}
-
-	if (baseDir) {
-		return resolve(baseDir, src);
-	}
-
-	return resolve(src);
-}
-
-/**
- * Extract the file extension from a path
- * @param path - File path
- * @returns File extension (including the dot)
- */
-export function getExtension(path: string) {
-	const match = /\.[^.]+$/.exec(path);
-	return match ? match[0] : '';
-}
-
-/**
- * Check if a path matches any of the given extensions
- * @param path - File path to check
- * @param extensions - Array of extensions (e.g., [".tsx", ".jsx"])
- * @returns True if path matches any extension
- */
-export function hasExtension(path: string, extensions: string[]) {
-	const ext = getExtension(path);
-	return extensions.includes(ext);
-}
-
-/**
- * Generate a unique scope ID for a component (useful for CSS scoping)
- * @param src - Source path to component
- * @returns Unique scope identifier
- */
-export function generateScopeId(src: string) {
-	// Create a simple hash from the path
-	const hash = src
-		.replaceAll(/[^a-zA-Z0-9]/g, '')
-		.toLowerCase()
-		.slice(-8);
-
-	return `data-v-${hash}`;
-}
-
-/**
- * Serialize props for client-side hydration
- * @param props - Props object to serialize
- * @returns JSON string safe for HTML attributes
- */
-export function serializeProps(props: Record<string, unknown>) {
-	try {
-		return JSON.stringify(props)
-			.replaceAll('<', String.raw`\u003c`)
-			.replaceAll('>', String.raw`\u003e`)
-			.replaceAll('&', String.raw`\u0026`)
-			.replaceAll("'", String.raw`\u0027`)
-			.replaceAll('"', String.raw`\u0022`);
-	} catch (error) {
-		console.error('Failed to serialize props:', error);
-		return '{}';
-	}
-}
-
-/**
- * Deserialize props from a JSON string
- * @param propsString - JSON string to deserialize
- * @returns Deserialized props object
- */
-export function deserializeProps(propsString: string) {
-	try {
-		return JSON.parse(propsString);
-	} catch (error) {
-		console.error('Failed to deserialize props:', error);
-		return {};
-	}
-}
-
-/**
- * Create a load context from environment and parameters
- * @param viteServer - Optional Vite dev server
- * @param buildOutput - Optional build output directory
- * @returns Load context object
- */
-export function createLoadContext(viteServer?: ViteDevServer, buildOutput?: string) {
-	const isDev = process.env.NODE_ENV !== 'production';
-
-	return {
-		isDev,
-		viteServer: isDev ? viteServer : undefined,
-		buildOutput: isDev ? undefined : buildOutput,
-	} satisfies LoadContext;
-}
-
-/**
- * Escape HTML special characters in a string
- * @param str - String to escape
- * @returns Escaped string
- */
-export function escapeHtml(str: string) {
-	return str
-		.replaceAll('&', '&amp;')
-		.replaceAll('<', '&lt;')
-		.replaceAll('>', '&gt;')
-		.replaceAll('"', '&quot;')
-		.replaceAll("'", '&#39;');
-}
-
-/**
- * Check if a module has a default export
- * @param module - Module to check
- * @returns True if module has a default export
- */
-export function hasDefaultExport(module: unknown) {
-	return module !== null && typeof module === 'object' && 'default' in module;
-}
-
-/**
- * Get the component from a module (handles default and named exports)
- * @param module - Module to extract component from
- * @returns The component
- */
-export function getComponentFromModule(module: Record<string, unknown>) {
-	if (hasDefaultExport(module)) {
-		return (module as Record<string, unknown>).default;
-	}
-
-	// If no default export, return the module itself
-	// (some frameworks export the component directly)
-	return module;
-}
-
-/**
- * Converts an absolute file path to a valid ESM import specifier.
- * Windows absolute paths (C:\...) are converted to file:// URLs.
- * On Unix, the path is returned as-is (no-op).
- *
- * This ensures dynamic import() calls work cross-platform.
- *
- * @param filePath - Absolute file path to convert
- * @returns A valid ESM import specifier
- */
-export function toImportSpecifier(filePath: string): string {
-	if (/^[A-Za-z]:[\\/]/.test(filePath)) {
-		return `file:///${filePath.replaceAll('\\', '/')}`;
-	}
-	return filePath;
-}
+/**
+ * Common utilities for framework integrations.
+ * Provides shared functionality for component loading, path resolution, and more.
+ */
+
+import type { ComponentLoadOptions, LoadContext } from './types.ts';
+import type { ViteDevServer } from 'vite';
+import { join, resolve } from 'node:path';
+
+/**
+ * Load a component module in development or production
+ * @param options - Component load options
+ * @returns The loaded component module
+ */
+export async function loadComponent(options: ComponentLoadOptions) {
+	const { src, context, target = 'ssr' } = options;
+
+	if (context.isDev && context.viteServer) {
+		return await loadComponentDev(src, context.viteServer);
+	}
+
+	return await loadComponentProd(src, context.buildOutput, target);
+}
+
+/**
+ * Load a component in development mode using Vite's SSR loader
+ * @param src - Source path to component
+ * @param viteServer - Vite dev server instance
+ * @returns The loaded component module
+ */
+async function loadComponentDev(src: string, viteServer: ViteDevServer) {
+	try {
+		const module = await viteServer.ssrLoadModule(src);
+		return module.default || module;
+	} catch (error) {
+		throw new Error(`Failed to load component in development: ${src}`, { cause: error });
+	}
+}
+
+/**
+ * Load a component in production mode from build output
+ * @param src - Source path to component
+ * @param buildOutput - Path to build output directory
+ * @param target - Whether loading for SSR or client
+ * @returns The loaded component module
+ */
+async function loadComponentProd(src: string, buildOutput: string | undefined, target: 'ssr' | 'client') {
+	const outputPath = resolveProductionPath(src, buildOutput, target);
+
+	try {
+		const module = await import(/* @vite-ignore */ toImportSpecifier(outputPath));
+		return module.default || module;
+	} catch (error) {
+		throw new Error(`Failed to load component in production: ${outputPath}`, { cause: error });
+	}
+}
+
+/**
+ * Resolve the production build path for a component
+ * @param src - Source path to component
+ * @param buildOutput - Path to build output directory
+ * @param target - Whether loading for SSR or client
+ * @returns Resolved path to built component
+ */
+export function resolveProductionPath(src: string, buildOutput: string | undefined, target: 'ssr' | 'client') {
+	const base = buildOutput || 'dist';
+	const targetDir = target === 'ssr' ? 'ssr' : 'client';
+
+	// Convert source path to output path
+	// e.g., /islands/Counter.tsx -> /dist/ssr/islands/Counter.js
+	const outputPath = src
+		.replace(/^\//, '') // Remove leading slash
+		.replace(/\.(tsx|jsx|ts|js|vue|svelte)$/, '.js'); // Change extension to .js
+
+	return join(base, targetDir, outputPath);
+}
+
+/**
+ * Normalize a component path to be absolute
+ * @param src - Source path (may be relative or absolute)
+ * @param baseDir - Base directory to resolve relative paths from
+ * @returns Absolute path
+ */
+export function normalizePath(src: string, baseDir?: string) {
+	if (src.startsWith('/') || src.startsWith('file://')) {
+		return src;
+	}
+
+	if (baseDir) {
+		return resolve(baseDir, src);
+	}
+
+	return resolve(src);
+}
+
+/**
+ * Extract the file extension from a path
+ * @param path - File path
+ * @returns File extension (including the dot)
+ */
+export function getExtension(path: string) {
+	const match = /\.[^.]+$/.exec(path);
+	return match ? match[0] : '';
+}
+
+/**
+ * Check if a path matches any of the given extensions
+ * @param path - File path to check
+ * @param extensions - Array of extensions (e.g., [".tsx", ".jsx"])
+ * @returns True if path matches any extension
+ */
+export function hasExtension(path: string, extensions: string[]) {
+	const ext = getExtension(path);
+	return extensions.includes(ext);
+}
+
+/**
+ * Generate a unique scope ID for a component (useful for CSS scoping)
+ * @param src - Source path to component
+ * @returns Unique scope identifier
+ */
+export function generateScopeId(src: string) {
+	// Create a simple hash from the path
+	const hash = src
+		.replaceAll(/[^a-zA-Z0-9]/g, '')
+		.toLowerCase()
+		.slice(-8);
+
+	return `data-v-${hash}`;
+}
+
+/**
+ * Serialize props for client-side hydration
+ * @param props - Props object to serialize
+ * @returns JSON string safe for HTML attributes
+ */
+export function serializeProps(props: Record<string, unknown>) {
+	try {
+		return JSON.stringify(props)
+			.replaceAll('<', String.raw`\u003c`)
+			.replaceAll('>', String.raw`\u003e`)
+			.replaceAll('&', String.raw`\u0026`)
+			.replaceAll("'", String.raw`\u0027`)
+			.replaceAll('"', String.raw`\u0022`);
+	} catch (error) {
+		console.error('Failed to serialize props:', error);
+		return '{}';
+	}
+}
+
+/**
+ * Deserialize props from a JSON string
+ * @param propsString - JSON string to deserialize
+ * @returns Deserialized props object
+ */
+export function deserializeProps(propsString: string) {
+	try {
+		return JSON.parse(propsString);
+	} catch (error) {
+		console.error('Failed to deserialize props:', error);
+		return {};
+	}
+}
+
+/**
+ * Create a load context from environment and parameters
+ * @param viteServer - Optional Vite dev server
+ * @param buildOutput - Optional build output directory
+ * @returns Load context object
+ */
+export function createLoadContext(viteServer?: ViteDevServer, buildOutput?: string) {
+	const isDev = process.env.NODE_ENV !== 'production';
+
+	return {
+		isDev,
+		viteServer: isDev ? viteServer : undefined,
+		buildOutput: isDev ? undefined : buildOutput,
+	} satisfies LoadContext;
+}
+
+/**
+ * Escape HTML special characters in a string
+ * @param str - String to escape
+ * @returns Escaped string
+ */
+export function escapeHtml(str: string) {
+	return str
+		.replaceAll('&', '&amp;')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;')
+		.replaceAll('"', '&quot;')
+		.replaceAll("'", '&#39;');
+}
+
+/**
+ * Check if a module has a default export
+ * @param module - Module to check
+ * @returns True if module has a default export
+ */
+export function hasDefaultExport(module: unknown) {
+	return module !== null && typeof module === 'object' && 'default' in module;
+}
+
+/**
+ * Get the component from a module (handles default and named exports)
+ * @param module - Module to extract component from
+ * @returns The component
+ */
+export function getComponentFromModule(module: Record<string, unknown>) {
+	if (hasDefaultExport(module)) {
+		return (module as Record<string, unknown>).default;
+	}
+
+	// If no default export, return the module itself
+	// (some frameworks export the component directly)
+	return module;
+}
+
+/**
+ * Converts an absolute file path to a valid ESM import specifier.
+ * Windows absolute paths (C:\...) are converted to file:// URLs.
+ * On Unix, the path is returned as-is (no-op).
+ *
+ * This ensures dynamic import() calls work cross-platform.
+ *
+ * @param filePath - Absolute file path to convert
+ * @returns A valid ESM import specifier
+ */
+export function toImportSpecifier(filePath: string): string {
+	if (/^[A-Za-z]:[\\/]/.test(filePath)) {
+		return `file:///${filePath.replaceAll('\\', '/')}`;
+	}
+	return filePath;
+}

package/vitest.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    root: import.meta.dirname,
-    include: ['__tests__/**/*.test.ts'],
-    server: {
-      deps: {
-        inline: ['zod'],
-      },
-    },
-  },
-});