@useavalon/avalon 0.1.11 → 0.1.13

package/src/vite-plugin/plugin.ts

@@ -1,409 +1,403 @@
-/**
- * Avalon Vite Plugin
- *
- * This module provides the main `avalon()` function that creates a unified Vite plugin
- * for the Avalon framework. It handles configuration resolution, integration activation,
- * Nitro server integration, and wires up all the necessary Vite hooks.
- * 
- * ISLAND DETECTION:
- * Islands are detected by usage - any component used with an `island` prop in pages
- * or layouts is automatically treated as an island. No fixed islands directory required.
- */
-
-import type { Plugin, PluginOption, ResolvedConfig, ViteDevServer } from "vite";
-import type {
-  AvalonPluginConfig,
-  IntegrationName,
-  ResolvedAvalonConfig,
-} from "./types.ts";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { resolveConfig, checkDirectoriesExist } from "./config.ts";
-import { activateIntegrations, activateSingleIntegration } from "./integration-activator.ts";
-import { discoverIntegrationsFromIslandUsage } from "./auto-discover.ts";
-import { validateActiveIntegrations, formatValidationResults } from "./validation.ts";
-import { createMDXPlugin } from "../build/mdx-plugin.ts";
-import { mdxIslandTransform } from "../build/mdx-island-transform.ts";
-import { pageIslandTransform } from "../build/page-island-transform.ts";
-import { registry } from "../core/integrations/registry.ts";
-import { createNitroIntegration } from "./nitro-integration.ts";
-import { islandSidecarPlugin } from "./island-sidecar-plugin.ts";
-import { createImagePlugin } from "./image-optimization.ts";
-import type { NitroConfigOutput } from "../nitro/config.ts";
-declare global {
-  var __avalonConfig: ResolvedAvalonConfig | undefined;
-  var __viteDevServer: ViteDevServer | undefined;
-  var __nitroConfig: NitroConfigOutput | undefined;
-}
-
-/**
- * Collects Vite plugins from all activated integrations.
- * 
- * This function iterates through the activated integrations and calls their
- * vitePlugin() method if implemented. The returned plugins are collected and
- * flattened into a single array.
- * 
- * Plugin ordering is handled to ensure correct application:
- * - Lit plugins come first (DOM shim requirement)
- * - Other framework plugins follow
- * 
- * @param activeIntegrations - Set of activated integration names
- * @param verbose - Whether to log detailed information
- * @returns Promise resolving to an array of Vite plugins from integrations
- */
-export async function collectIntegrationPlugins(
-  activeIntegrations: Set<IntegrationName>,
-  verbose: boolean = false
-): Promise<Plugin[]> {
-  const plugins: Plugin[] = [];
-  const litPlugins: Plugin[] = [];
-
-  for (const name of activeIntegrations) {
-    const validPlugins = await loadPluginsForIntegration(name, verbose);
-    if (name === "lit") {
-      litPlugins.push(...validPlugins);
-    } else {
-      plugins.push(...validPlugins);
-    }
-  }
-
-  return [...litPlugins, ...plugins];
-}
-
-async function loadPluginsForIntegration(name: IntegrationName, _verbose: boolean): Promise<Plugin[]> {
-  const integration = registry.get(name);
-  if (!integration) return [];
-  if (typeof integration.vitePlugin !== "function") return [];
-
-  try {
-    const result = await integration.vitePlugin();
-    const pluginArray = Array.isArray(result) ? result : [result];
-    return pluginArray.filter((p): p is Plugin => p != null);
-  } catch (error) {
-    console.warn(`[avalon] Failed to load vite plugin for ${name}:`, error instanceof Error ? error.message : error);
-    return [];
-  }
-}
-
-/**
- * Discovers which integrations are actually needed by scanning pages/layouts for island prop usage.
- * This enables lazy loading - only load Vite plugins for frameworks that are actually used.
- * 
- * @param config - The resolved Avalon configuration
- * @param projectRoot - The project root directory (defaults to cwd)
- * @returns Set of integration names that are actually needed
- */
-async function discoverNeededIntegrations(
-  config: ResolvedAvalonConfig,
-  projectRoot?: string
-): Promise<Set<IntegrationName>> {
-  const needed = new Set<IntegrationName>();
-  
-  try {
-    // Scan pages, layouts, and modules for components used with island prop
-    const discovered = await discoverIntegrationsFromIslandUsage(
-      config.pagesDir,
-      config.layoutsDir,
-      projectRoot,
-      config.modules?.dir
-    );
-    
-    // Only include integrations that are both discovered AND configured
-    for (const integration of discovered) {
-      if (config.integrations.includes(integration)) {
-        needed.add(integration);
-      }
-    }
-  } catch {
-    // If discovery fails, fall back to all configured integrations
-    for (const integration of config.integrations) {
-      needed.add(integration);
-    }
-  }
-  
-  return needed;
-}
-
-async function resolveIntegrationsToLoad(
-  preResolvedConfig: ResolvedAvalonConfig
-): Promise<IntegrationName[]> {
-  if (!preResolvedConfig.lazyIntegrations || preResolvedConfig.integrations.length === 0) {
-    return [...preResolvedConfig.integrations];
-  }
-
-  const needed = await discoverNeededIntegrations(preResolvedConfig);
-  if (needed.size === 0) {
-    return [...preResolvedConfig.integrations];
-  }
-
-  return Array.from(needed);
-}
-
-async function setupMDXPlugins(preResolvedConfig: ResolvedAvalonConfig): Promise<Plugin[]> {
-  try {
-    const mdxPlugins = await createMDXPlugin({
-      jsxImportSource: preResolvedConfig.mdx.jsxImportSource,
-      syntaxHighlighting: preResolvedConfig.mdx.syntaxHighlighting,
-      remarkPlugins: preResolvedConfig.mdx.remarkPlugins as import("unified").Pluggable[],
-      rehypePlugins: preResolvedConfig.mdx.rehypePlugins as import("unified").Pluggable[],
-      development: true,
-    });
-    mdxPlugins.push(mdxIslandTransform({ verbose: preResolvedConfig.verbose }));
-    return mdxPlugins;
-  } catch (error) {
-    if (preResolvedConfig.showWarnings) {
-      console.warn("⚠️ Could not configure MDX plugin:", error);
-    }
-    return [];
-  }
-}
-
-function setupNitroPlugins(
-  preResolvedConfig: ResolvedAvalonConfig,
-  nitroConfig: NonNullable<AvalonPluginConfig["nitro"]>,
-  _verbose?: boolean
-): { plugins: Plugin[]; options: NitroConfigOutput } {
-  const { plugins, nitroOptions } = createNitroIntegration(preResolvedConfig, nitroConfig);
-  globalThis.__nitroConfig = nitroOptions;
-  return { plugins, options: nitroOptions };
-}
-
-async function runAutoDiscovery(
-  resolvedConfig: ResolvedAvalonConfig,
-  viteRoot: string,
-  activeIntegrations: Set<IntegrationName>
-): Promise<void> {
-  if (!resolvedConfig.autoDiscoverIntegrations) return;
-
-  try {
-    const discovered = await discoverIntegrationsFromIslandUsage(
-      resolvedConfig.pagesDir,
-      resolvedConfig.layoutsDir,
-      viteRoot,
-      resolvedConfig.modules?.dir
-    );
-    for (const name of discovered) {
-      if (activeIntegrations.has(name)) continue;
-      try {
-        await activateSingleIntegration(name, activeIntegrations, resolvedConfig.verbose);
-      } catch (error) {
-        if (resolvedConfig.showWarnings) console.warn(`   ⚠️ Could not auto-load integration: ${name}`, error);
-      }
-    }
-  } catch (error) {
-    if (resolvedConfig.showWarnings) console.warn("   ⚠️ Auto-discovery failed:", error);
-  }
-}
-
-function runValidation(
-  resolvedConfig: ResolvedAvalonConfig,
-  activeIntegrations: Set<IntegrationName>
-): void {
-  if (!resolvedConfig.validateIntegrations || activeIntegrations.size === 0) return;
-
-  const validationSummary = validateActiveIntegrations(activeIntegrations, resolvedConfig.showWarnings);
-  if (!validationSummary.allValid) {
-    console.error(formatValidationResults(validationSummary));
-    if (resolvedConfig.showWarnings) console.warn("   ⚠️ Some integrations have validation issues.");
-  }
-}
-
-/**
- * Creates the Avalon Vite plugin array
- *
- * @param config - Avalon configuration options
- * @returns A promise that resolves to an array of Vite plugins that handle all Avalon functionality.
- *          Returns PluginOption[] to avoid TypeScript's excessive stack depth issues
- *          when comparing Plugin<any> arrays in Vite 8's complex type system.
- */
-export async function avalon(config?: AvalonPluginConfig): Promise<PluginOption[]> {
-  // Resolved configuration with defaults applied
-  let resolvedConfig: ResolvedAvalonConfig;
-
-  // Reference to Vite's resolved config
-  let viteConfig: ResolvedConfig;
-
-  // Track which integrations are activated
-  const activeIntegrations = new Set<IntegrationName>();
-
-  // Pre-resolve config to get MDX settings and integration list
-  // We use isDev=true as a default; the actual value will be set in configResolved
-  const preResolvedConfig = resolveConfig(config, true);
-
-  const integrationsToLoad = await resolveIntegrationsToLoad(preResolvedConfig);
-
-  if (integrationsToLoad.length > 0) {
-    await activateIntegrations({ ...preResolvedConfig, integrations: integrationsToLoad }, activeIntegrations);
-  }
-  const mdxPlugins = await setupMDXPlugins(preResolvedConfig);
-
-  // Image optimization plugins (vite-imagetools wrapper)
-  const imagePlugins = await createImagePlugin(preResolvedConfig.image, preResolvedConfig.verbose);
-
-  let integrationPlugins: Plugin[] = [];
-  if (activeIntegrations.size > 0) {
-    integrationPlugins = await collectIntegrationPlugins(activeIntegrations, preResolvedConfig.verbose);
-  }
-
-  let nitroPlugins: Plugin[] = [];
-  if (config?.nitro) {
-    const { plugins } = setupNitroPlugins(preResolvedConfig, config.nitro, preResolvedConfig.verbose);
-    nitroPlugins = plugins;
-  }
-
-  // Sidecar plugin for Vue/Svelte/Solid type declarations
-  const sidecarPlugin = islandSidecarPlugin({
-    verbose: preResolvedConfig.verbose,
-  });
-
-  // Pre-resolve paths for standalone projects.
-  // In the monorepo www/ project these are handled by manual resolve.alias.
-  const require = createRequire(import.meta.url);
-
-  let clientMainResolved: string | null = null;
-  try {
-    const clientEntry = require.resolve("@useavalon/avalon/client");
-    clientMainResolved = join(dirname(clientEntry), "main.js");
-  } catch {
-    // Monorepo — www/ sets its own alias
-  }
-
-  // Resolve /@useavalon/*/client virtual imports used by main.js
-  // These are resolved dynamically in the resolveId hook using Vite's resolver
-  const integrationClientIds = new Set(
-    ['preact', 'react', 'vue', 'svelte', 'solid', 'lit', 'qwik'].map(
-      name => `/@useavalon/${name}/client`
-    )
-  );
-
-  // The main Avalon plugin
-  const avalonPlugin: Plugin = {
-    name: "avalon",
-    enforce: "pre",
-
-    config() {
-      // @useavalon packages ship raw .ts source for SSR and pre-compiled
-      // .js for client-side code.
-      //
-      // oxc.exclude: Prevents Vite's built-in OXC from processing @useavalon
-      //   .ts files. Without this, OXC applies integration plugins' global
-      //   jsx: 'automatic' config to plain .ts files, causing errors.
-      //   Our transform hook below handles TS stripping for SSR instead.
-      //   Client-side loads .js files which OXC skips by default (/\.js$/).
-      //
-      // ssr.noExternal: Ensures Vite processes @useavalon packages through
-      //   the SSR transform pipeline instead of treating them as external CJS.
-      return {
-        oxc: {
-          exclude: [/node_modules\/@useavalon\/.*\.tsx?$/],
-        },
-        ssr: {
-          noExternal: [/^@useavalon\//],
-        },
-      };
-    },
-
-    configResolved(resolvedViteConfig: ResolvedConfig) {
-      viteConfig = resolvedViteConfig;
-      const isDev = resolvedViteConfig.command === "serve";
-      resolvedConfig = resolveConfig(config, isDev);
-
-      globalThis.__avalonConfig = resolvedConfig;
-
-      checkDirectoriesExist(resolvedConfig, resolvedViteConfig.root);
-    },
-
-    async resolveId(id: string) {
-      if (id === "/src/client/main.js" && clientMainResolved) {
-        return clientMainResolved;
-      }
-      // /@useavalon/*/client — resolve through Vite's pipeline so it finds
-      // workspace-linked or npm-installed integration packages from the
-      // consuming project's node_modules, not from avalon's own context.
-      if (integrationClientIds.has(id)) {
-        const packageId = id.slice(1); // strip leading /
-        const resolved = await this.resolve(packageId);
-        return resolved?.id ?? null;
-      }
-      return null;
-    },
-
-    async transform(code: string, id: string) {
-      // For SSR: strip TypeScript from @useavalon packages ourselves.
-      // Integration plugins (react, preact) set jsx: 'automatic' which Vite's
-      // OXC applies to all files — causing "Invalid jsx option" errors on
-      // plain .ts files during SSR. We intercept and strip TS without JSX config.
-      // For client-side: main.js imports pre-compiled .js files that OXC
-      // skips entirely (default exclude: /\.js$/), avoiding the jsx conflict.
-      if (
-        this.environment?.config?.consumer === 'server' &&
-        id.includes('@useavalon/') &&
-        /\.tsx?$/.test(id)
-      ) {
-        const { transform: oxcTransform } = await import('oxc-transform');
-        const result = await oxcTransform(id, code, {
-          sourcemap: true,
-          typescript: { onlyRemoveTypeImports: false },
-        });
-        return { code: result.code, map: result.map, moduleType: 'js' };
-      }
-    },
-
-    async buildStart() {
-      await runAutoDiscovery(resolvedConfig, viteConfig?.root, activeIntegrations);
-      runValidation(resolvedConfig, activeIntegrations);
-    },
-
-    configureServer(server: ViteDevServer) {
-      
-      (globalThis as any).__viteDevServer = server;
-    },
-  };
-
-  // Extract Lit plugins for proper ordering
-  const litPlugins = integrationPlugins.filter(p => p.name?.includes("lit"));
-  const otherIntegrationPlugins = integrationPlugins.filter(p => !p.name?.includes("lit"));
-
-  // Page island transform: auto-wraps components with `island` prop
-  const pageTransformPlugin = pageIslandTransform({
-    pagesDir: preResolvedConfig.pagesDir,
-    layoutsDir: preResolvedConfig.layoutsDir,
-    modules: preResolvedConfig.modules,
-    verbose: preResolvedConfig.verbose,
-  });
-
-  return [
-    pageTransformPlugin,
-    ...imagePlugins,
-    ...litPlugins,
-    ...mdxPlugins,
-    avalonPlugin,
-    sidecarPlugin,
-    ...nitroPlugins,
-    ...otherIntegrationPlugins,
-  ] as PluginOption[];
-}
-
-export function getResolvedConfig(): ResolvedAvalonConfig | undefined {
-  return globalThis.__avalonConfig;
-}
-
-export function getPagesDir(): string {
-  return globalThis.__avalonConfig?.pagesDir ?? "src/pages";
-}
-
-export function getLayoutsDir(): string {
-  return globalThis.__avalonConfig?.layoutsDir ?? "src/layouts";
-}
-
-
-export function getNitroConfig(): NitroConfigOutput | undefined {
-  return globalThis.__nitroConfig;
-}
-
-export function isNitroEnabled(): boolean {
-  return globalThis.__nitroConfig !== undefined;
-}
-
-export type { AvalonPluginConfig, IntegrationName, ResolvedAvalonConfig, ImageConfig, ResolvedImageConfig } from "./types.ts";
-export type { AvalonNitroConfig, NitroConfigOutput } from "../nitro/config.ts";
+/**
+ * Avalon Vite Plugin
+ *
+ * This module provides the main `avalon()` function that creates a unified Vite plugin
+ * for the Avalon framework. It handles configuration resolution, integration activation,
+ * Nitro server integration, and wires up all the necessary Vite hooks.
+ *
+ * ISLAND DETECTION:
+ * Islands are detected by usage - any component used with an `island` prop in pages
+ * or layouts is automatically treated as an island. No fixed islands directory required.
+ */
+
+import type { Plugin, PluginOption, ResolvedConfig, ViteDevServer } from 'vite';
+import type { AvalonPluginConfig, IntegrationName, ResolvedAvalonConfig } from './types.ts';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { resolveConfig, checkDirectoriesExist } from './config.ts';
+import { activateIntegrations, activateSingleIntegration } from './integration-activator.ts';
+import { discoverIntegrationsFromIslandUsage } from './auto-discover.ts';
+import { validateActiveIntegrations, formatValidationResults } from './validation.ts';
+import { createMDXPlugin } from '../build/mdx-plugin.ts';
+import { mdxIslandTransform } from '../build/mdx-island-transform.ts';
+import { pageIslandTransform } from '../build/page-island-transform.ts';
+import { registry } from '../core/integrations/registry.ts';
+import { createNitroIntegration } from './nitro-integration.ts';
+import { islandSidecarPlugin } from './island-sidecar-plugin.ts';
+import { createImagePlugin } from './image-optimization.ts';
+import type { NitroConfigOutput } from '../nitro/config.ts';
+declare global {
+	var __avalonConfig: ResolvedAvalonConfig | undefined;
+	var __viteDevServer: ViteDevServer | undefined;
+	var __nitroConfig: NitroConfigOutput | undefined;
+}
+
+/**
+ * Collects Vite plugins from all activated integrations.
+ *
+ * This function iterates through the activated integrations and calls their
+ * vitePlugin() method if implemented. The returned plugins are collected and
+ * flattened into a single array.
+ *
+ * Plugin ordering is handled to ensure correct application:
+ * - Lit plugins come first (DOM shim requirement)
+ * - Other framework plugins follow
+ *
+ * @param activeIntegrations - Set of activated integration names
+ * @param verbose - Whether to log detailed information
+ * @returns Promise resolving to an array of Vite plugins from integrations
+ */
+export async function collectIntegrationPlugins(
+	activeIntegrations: Set<IntegrationName>,
+	verbose: boolean = false,
+): Promise<Plugin[]> {
+	const plugins: Plugin[] = [];
+	const litPlugins: Plugin[] = [];
+
+	for (const name of activeIntegrations) {
+		const validPlugins = await loadPluginsForIntegration(name, verbose);
+		if (name === 'lit') {
+			litPlugins.push(...validPlugins);
+		} else {
+			plugins.push(...validPlugins);
+		}
+	}
+
+	return [...litPlugins, ...plugins];
+}
+
+async function loadPluginsForIntegration(name: IntegrationName, _verbose: boolean): Promise<Plugin[]> {
+	const integration = registry.get(name);
+	if (!integration) return [];
+	if (typeof integration.vitePlugin !== 'function') return [];
+
+	try {
+		const result = await integration.vitePlugin();
+		const pluginArray = Array.isArray(result) ? result : [result];
+		return pluginArray.filter((p): p is Plugin => p != null);
+	} catch (error) {
+		console.warn(`[avalon] Failed to load vite plugin for ${name}:`, error instanceof Error ? error.message : error);
+		return [];
+	}
+}
+
+/**
+ * Discovers which integrations are actually needed by scanning pages/layouts for island prop usage.
+ * This enables lazy loading - only load Vite plugins for frameworks that are actually used.
+ *
+ * @param config - The resolved Avalon configuration
+ * @param projectRoot - The project root directory (defaults to cwd)
+ * @returns Set of integration names that are actually needed
+ */
+async function discoverNeededIntegrations(
+	config: ResolvedAvalonConfig,
+	projectRoot?: string,
+): Promise<Set<IntegrationName>> {
+	const needed = new Set<IntegrationName>();
+
+	try {
+		// Scan pages, layouts, and modules for components used with island prop
+		const discovered = await discoverIntegrationsFromIslandUsage(
+			config.pagesDir,
+			config.layoutsDir,
+			projectRoot,
+			config.modules?.dir,
+		);
+
+		// Only include integrations that are both discovered AND configured
+		for (const integration of discovered) {
+			if (config.integrations.includes(integration)) {
+				needed.add(integration);
+			}
+		}
+	} catch {
+		// If discovery fails, fall back to all configured integrations
+		for (const integration of config.integrations) {
+			needed.add(integration);
+		}
+	}
+
+	return needed;
+}
+
+async function resolveIntegrationsToLoad(preResolvedConfig: ResolvedAvalonConfig): Promise<IntegrationName[]> {
+	if (!preResolvedConfig.lazyIntegrations || preResolvedConfig.integrations.length === 0) {
+		return [...preResolvedConfig.integrations];
+	}
+
+	const needed = await discoverNeededIntegrations(preResolvedConfig);
+	if (needed.size === 0) {
+		return [...preResolvedConfig.integrations];
+	}
+
+	return Array.from(needed);
+}
+
+async function setupMDXPlugins(preResolvedConfig: ResolvedAvalonConfig): Promise<Plugin[]> {
+	try {
+		const mdxPlugins = await createMDXPlugin({
+			jsxImportSource: preResolvedConfig.mdx.jsxImportSource,
+			syntaxHighlighting: preResolvedConfig.mdx.syntaxHighlighting,
+			remarkPlugins: preResolvedConfig.mdx.remarkPlugins as import('unified').Pluggable[],
+			rehypePlugins: preResolvedConfig.mdx.rehypePlugins as import('unified').Pluggable[],
+			development: true,
+		});
+		mdxPlugins.push(mdxIslandTransform({ verbose: preResolvedConfig.verbose }));
+		return mdxPlugins;
+	} catch (error) {
+		if (preResolvedConfig.showWarnings) {
+			console.warn('⚠️ Could not configure MDX plugin:', error);
+		}
+		return [];
+	}
+}
+
+function setupNitroPlugins(
+	preResolvedConfig: ResolvedAvalonConfig,
+	nitroConfig: NonNullable<AvalonPluginConfig['nitro']>,
+	_verbose?: boolean,
+): { plugins: Plugin[]; options: NitroConfigOutput } {
+	const { plugins, nitroOptions } = createNitroIntegration(preResolvedConfig, nitroConfig);
+	globalThis.__nitroConfig = nitroOptions;
+	return { plugins, options: nitroOptions };
+}
+
+async function runAutoDiscovery(
+	resolvedConfig: ResolvedAvalonConfig,
+	viteRoot: string,
+	activeIntegrations: Set<IntegrationName>,
+): Promise<void> {
+	if (!resolvedConfig.autoDiscoverIntegrations) return;
+
+	try {
+		const discovered = await discoverIntegrationsFromIslandUsage(
+			resolvedConfig.pagesDir,
+			resolvedConfig.layoutsDir,
+			viteRoot,
+			resolvedConfig.modules?.dir,
+		);
+		for (const name of discovered) {
+			if (activeIntegrations.has(name)) continue;
+			try {
+				await activateSingleIntegration(name, activeIntegrations, resolvedConfig.verbose);
+			} catch (error) {
+				if (resolvedConfig.showWarnings) console.warn(`   ⚠️ Could not auto-load integration: ${name}`, error);
+			}
+		}
+	} catch (error) {
+		if (resolvedConfig.showWarnings) console.warn('   ⚠️ Auto-discovery failed:', error);
+	}
+}
+
+function runValidation(resolvedConfig: ResolvedAvalonConfig, activeIntegrations: Set<IntegrationName>): void {
+	if (!resolvedConfig.validateIntegrations || activeIntegrations.size === 0) return;
+
+	const validationSummary = validateActiveIntegrations(activeIntegrations, resolvedConfig.showWarnings);
+	if (!validationSummary.allValid) {
+		console.error(formatValidationResults(validationSummary));
+		if (resolvedConfig.showWarnings) console.warn('   ⚠️ Some integrations have validation issues.');
+	}
+}
+
+/**
+ * Creates the Avalon Vite plugin array
+ *
+ * @param config - Avalon configuration options
+ * @returns A promise that resolves to an array of Vite plugins that handle all Avalon functionality.
+ *          Returns PluginOption[] to avoid TypeScript's excessive stack depth issues
+ *          when comparing Plugin<any> arrays in Vite 8's complex type system.
+ */
+export async function avalon(config?: AvalonPluginConfig): Promise<PluginOption[]> {
+	// Resolved configuration with defaults applied
+	let resolvedConfig: ResolvedAvalonConfig;
+
+	// Reference to Vite's resolved config
+	let viteConfig: ResolvedConfig;
+
+	// Track which integrations are activated
+	const activeIntegrations = new Set<IntegrationName>();
+
+	// Pre-resolve config to get MDX settings and integration list
+	// We use isDev=true as a default; the actual value will be set in configResolved
+	const preResolvedConfig = resolveConfig(config, true);
+
+	const integrationsToLoad = await resolveIntegrationsToLoad(preResolvedConfig);
+
+	if (integrationsToLoad.length > 0) {
+		await activateIntegrations({ ...preResolvedConfig, integrations: integrationsToLoad }, activeIntegrations);
+	}
+	const mdxPlugins = await setupMDXPlugins(preResolvedConfig);
+
+	// Image optimization plugins (vite-imagetools wrapper)
+	const imagePlugins = await createImagePlugin(preResolvedConfig.image, preResolvedConfig.verbose);
+
+	let integrationPlugins: Plugin[] = [];
+	if (activeIntegrations.size > 0) {
+		integrationPlugins = await collectIntegrationPlugins(activeIntegrations, preResolvedConfig.verbose);
+	}
+
+	let nitroPlugins: Plugin[] = [];
+	if (config?.nitro) {
+		const { plugins } = setupNitroPlugins(preResolvedConfig, config.nitro, preResolvedConfig.verbose);
+		nitroPlugins = plugins;
+	}
+
+	// Sidecar plugin for Vue/Svelte/Solid type declarations
+	const sidecarPlugin = islandSidecarPlugin({
+		verbose: preResolvedConfig.verbose,
+	});
+
+	// Pre-resolve paths for standalone projects.
+	// In the monorepo www/ project these are handled by manual resolve.alias.
+	const require = createRequire(import.meta.url);
+
+	let clientMainResolved: string | null = null;
+	try {
+		const clientEntry = require.resolve('@useavalon/avalon/client');
+		clientMainResolved = join(dirname(clientEntry), 'main.js');
+	} catch {
+		// Monorepo — www/ sets its own alias
+	}
+
+	// Resolve /@useavalon/*/client and /@useavalon/*/client/hmr virtual imports
+	// used by main.js. These are resolved dynamically in the resolveId hook
+	// using Vite's resolver.
+	const integrationVirtualIds = new Set(
+		['preact', 'react', 'vue', 'svelte', 'solid', 'lit', 'qwik'].flatMap(name => [
+			`/@useavalon/${name}/client`,
+			`/@useavalon/${name}/client/hmr`,
+		]),
+	);
+
+	// The main Avalon plugin
+	const avalonPlugin: Plugin = {
+		name: 'avalon',
+		enforce: 'pre',
+
+		config() {
+			// @useavalon packages ship raw .ts source for SSR and pre-compiled
+			// .js for client-side code.
+			//
+			// oxc.exclude: Prevents Vite's built-in OXC from processing @useavalon
+			//   .ts files. Without this, OXC applies integration plugins' global
+			//   jsx: 'automatic' config to plain .ts files, causing errors.
+			//   Our transform hook below handles TS stripping for SSR instead.
+			//   Client-side loads .js files which OXC skips by default (/\.js$/).
+			//
+			// ssr.noExternal: Ensures Vite processes @useavalon packages through
+			//   the SSR transform pipeline instead of treating them as external CJS.
+			return {
+				oxc: {
+					exclude: [/node_modules\/@useavalon\/.*\.tsx?$/],
+				},
+				ssr: {
+					noExternal: [/^@useavalon\//],
+				},
+			};
+		},
+
+		configResolved(resolvedViteConfig: ResolvedConfig) {
+			viteConfig = resolvedViteConfig;
+			const isDev = resolvedViteConfig.command === 'serve';
+			resolvedConfig = resolveConfig(config, isDev);
+
+			globalThis.__avalonConfig = resolvedConfig;
+
+			checkDirectoriesExist(resolvedConfig, resolvedViteConfig.root);
+		},
+
+		async resolveId(id: string) {
+			if (id === '/src/client/main.js' && clientMainResolved) {
+				return clientMainResolved;
+			}
+			// /@useavalon/*/client and /@useavalon/*/client/hmr — resolve through
+			// Vite's pipeline so it finds workspace-linked or npm-installed
+			// integration packages from the consuming project's node_modules,
+			// not from avalon's own context.
+			if (integrationVirtualIds.has(id)) {
+				const packageId = id.slice(1); // strip leading /
+				const resolved = await this.resolve(packageId);
+				return resolved?.id ?? null;
+			}
+			return null;
+		},
+
+		async transform(code: string, id: string) {
+			// For SSR: strip TypeScript from @useavalon packages ourselves.
+			// Integration plugins (react, preact) set jsx: 'automatic' which Vite's
+			// OXC applies to all files — causing "Invalid jsx option" errors on
+			// plain .ts files during SSR. We intercept and strip TS without JSX config.
+			// For client-side: main.js imports pre-compiled .js files that OXC
+			// skips entirely (default exclude: /\.js$/), avoiding the jsx conflict.
+			if (this.environment?.config?.consumer === 'server' && id.includes('@useavalon/') && /\.tsx?$/.test(id)) {
+				const { transform: oxcTransform } = await import('oxc-transform');
+				const result = await oxcTransform(id, code, {
+					sourcemap: true,
+					typescript: { onlyRemoveTypeImports: false },
+				});
+				return { code: result.code, map: result.map, moduleType: 'js' };
+			}
+		},
+
+		async buildStart() {
+			await runAutoDiscovery(resolvedConfig, viteConfig?.root, activeIntegrations);
+			runValidation(resolvedConfig, activeIntegrations);
+		},
+
+		configureServer(server: ViteDevServer) {
+			(globalThis as any).__viteDevServer = server;
+		},
+	};
+
+	// Extract Lit plugins for proper ordering
+	const litPlugins = integrationPlugins.filter(p => p.name?.includes('lit'));
+	const otherIntegrationPlugins = integrationPlugins.filter(p => !p.name?.includes('lit'));
+
+	// Page island transform: auto-wraps components with `island` prop
+	const pageTransformPlugin = pageIslandTransform({
+		pagesDir: preResolvedConfig.pagesDir,
+		layoutsDir: preResolvedConfig.layoutsDir,
+		modules: preResolvedConfig.modules,
+		verbose: preResolvedConfig.verbose,
+	});
+
+	return [
+		pageTransformPlugin,
+		...imagePlugins,
+		...litPlugins,
+		...mdxPlugins,
+		avalonPlugin,
+		sidecarPlugin,
+		...nitroPlugins,
+		...otherIntegrationPlugins,
+	] as PluginOption[];
+}
+
+export function getResolvedConfig(): ResolvedAvalonConfig | undefined {
+	return globalThis.__avalonConfig;
+}
+
+export function getPagesDir(): string {
+	return globalThis.__avalonConfig?.pagesDir ?? 'src/pages';
+}
+
+export function getLayoutsDir(): string {
+	return globalThis.__avalonConfig?.layoutsDir ?? 'src/layouts';
+}
+
+export function getNitroConfig(): NitroConfigOutput | undefined {
+	return globalThis.__nitroConfig;
+}
+
+export function isNitroEnabled(): boolean {
+	return globalThis.__nitroConfig !== undefined;
+}
+
+export type {
+	AvalonPluginConfig,
+	IntegrationName,
+	ResolvedAvalonConfig,
+	ImageConfig,
+	ResolvedImageConfig,
+} from './types.ts';
+export type { AvalonNitroConfig, NitroConfigOutput } from '../nitro/config.ts';