@useavalon/avalon 0.1.0

package/src/vite-plugin/plugin.ts

@@ -0,0 +1,329 @@
+/**
+ * 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 { 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,
+  });
+
+  // The main Avalon plugin
+  const avalonPlugin: Plugin = {
+    name: "avalon",
+    enforce: "pre",
+
+    configResolved(resolvedViteConfig: ResolvedConfig) {
+      viteConfig = resolvedViteConfig;
+      const isDev = resolvedViteConfig.command === "serve";
+      resolvedConfig = resolveConfig(config, isDev);
+
+      globalThis.__avalonConfig = resolvedConfig;
+
+      checkDirectoriesExist(resolvedConfig, resolvedViteConfig.root);
+    },
+
+    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";

package/src/vite-plugin/tests/image-optimization.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createImagePlugin } from "../image-optimization.ts";
+import type { ResolvedImageConfig } from "../types.ts";
+
+describe("createImagePlugin", () => {
+  const defaultConfig: ResolvedImageConfig = {
+    enabled: true,
+    defaultFormat: "webp",
+    quality: 80,
+    widths: [200, 400, 600, 800, 1200],
+    removeMetadata: true,
+    include: /^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/,
+    exclude: "public/**/*",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns empty array when disabled", async () => {
+    const plugins = await createImagePlugin({ ...defaultConfig, enabled: false }, false);
+    expect(plugins).toEqual([]);
+  });
+
+  it("returns imagetools plugin when enabled", async () => {
+    const plugins = await createImagePlugin(defaultConfig, false);
+    expect(plugins.length).toBe(1);
+    expect(plugins[0].name).toBe("imagetools");
+  });
+
+  it("logs info when verbose is true", async () => {
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    
+    await createImagePlugin(defaultConfig, true);
+    
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Image optimization enabled"));
+    consoleSpy.mockRestore();
+  });
+
+  it("respects custom format setting", async () => {
+    const plugins = await createImagePlugin({ ...defaultConfig, defaultFormat: "avif" }, true);
+    expect(plugins.length).toBe(1);
+  });
+
+  it("respects custom quality setting", async () => {
+    const plugins = await createImagePlugin({ ...defaultConfig, quality: 90 }, false);
+    expect(plugins.length).toBe(1);
+  });
+
+  it("respects custom widths setting", async () => {
+    const plugins = await createImagePlugin({ ...defaultConfig, widths: [320, 640, 1280] }, false);
+    expect(plugins.length).toBe(1);
+  });
+});

package/src/vite-plugin/types.ts

@@ -0,0 +1,327 @@
+/**
+ * Vite Plugin Types for Avalon
+ *
+ * CONFIG PATH: Vite plugin runtime
+ * These types define the inline configuration passed to `avalon()` in
+ * `vite.config.ts`. The `resolveConfig()` function in `vite-plugin/config.ts`
+ * merges user options against `DEFAULT_CONFIG` to produce a `ResolvedAvalonConfig`.
+ *
+ * This path uses `IntegrationName[]` (simple string array) for integrations.
+ *
+ * There is a separate CLI config path (`schemas/integration-config.ts` →
+ * `config-loader.ts` → `startup.ts` → `cli.ts`) that reads `avalon.config.ts`
+ * from disk and uses `IntegrationConfigEntry[]` (objects with name/enabled/options).
+ * That path is NOT used during Vite plugin startup.
+ */
+
+import type { AvalonNitroConfig } from "../nitro/config.ts";
+
+/**
+ * Image optimization configuration
+ */
+export interface ImageConfig {
+  /**
+   * Enable image optimization via vite-imagetools
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Default image format for optimized images
+   * @default "webp"
+   */
+  defaultFormat?: "webp" | "avif" | "jpg" | "png";
+
+  /**
+   * Default image quality (1-100)
+   * @default 80
+   */
+  quality?: number;
+
+  /**
+   * Breakpoint widths for srcset generation
+   * @default [200, 400, 600, 800, 1200]
+   */
+  widths?: number[];
+
+  /**
+   * Whether to strip EXIF and other metadata from images
+   * @default true
+   */
+  removeMetadata?: boolean;
+
+  /**
+   * File patterns to include for image processing
+   * @default /^[^?]+\.(heif|avif|jpeg|jpg|png|tiff|webp|gif)(\?.*)?$/
+   */
+  include?: string | RegExp | (string | RegExp)[];
+
+  /**
+   * File patterns to exclude from image processing
+   * @default "public/**\/*"
+   */
+  exclude?: string | RegExp | (string | RegExp)[];
+}
+
+/**
+ * Resolved image optimization configuration
+ */
+export interface ResolvedImageConfig {
+  enabled: boolean;
+  defaultFormat: "webp" | "avif" | "jpg" | "png";
+  quality: number;
+  widths: number[];
+  removeMetadata: boolean;
+  include: string | RegExp | (string | RegExp)[];
+  exclude: string | RegExp | (string | RegExp)[];
+}
+
+/**
+ * Supported integration names
+ * These correspond to the @useavalon/* packages
+ */
+export type IntegrationName =
+  | "react"
+  | "preact"
+  | "vue"
+  | "svelte"
+  | "solid"
+  | "lit"
+  | "qwik";
+
+/**
+ * MDX configuration options
+ */
+export interface MDXConfig {
+  /**
+   * JSX import source for MDX files
+   * @default "preact"
+   */
+  jsxImportSource?: string;
+
+  /**
+   * Enable syntax highlighting for code blocks
+   * @default true
+   */
+  syntaxHighlighting?: boolean;
+
+  /**
+   * Custom remark plugins
+   */
+  remarkPlugins?: unknown[];
+
+  /**
+   * Custom rehype plugins
+   */
+  rehypePlugins?: unknown[];
+}
+
+/**
+ * Modular architecture configuration
+ * Enables co-located pages/layouts within feature modules
+ */
+export interface ModulesConfig {
+  /**
+   * Directory containing feature modules
+   * @example "app/modules"
+   */
+  dir: string;
+
+  /**
+   * Name of the pages directory within each module
+   * @default "pages"
+   */
+  pagesDirName?: string;
+
+  /**
+   * Name of the layouts directory within each module
+   * @default "layouts"
+   */
+  layoutsDirName?: string;
+}
+
+/**
+ * Configuration options for the Avalon Vite plugin
+ */
+export interface AvalonPluginConfig {
+  /**
+   * Directory containing page components for file-system routing
+   * @default "src/pages"
+   */
+  pagesDir?: string;
+
+  /**
+   * Directory containing layout components
+   * @default "src/layouts"
+   */
+  layoutsDir?: string;
+
+  /**
+   * Modular architecture configuration
+   * When set, discovers pages and layouts within feature modules
+   * Can be a string (just the dir) or full config object
+   * 
+   * @example
+   * ```ts
+   * // Simple - uses default 'pages' and 'layouts' folder names
+   * modules: 'app/modules'
+   * 
+   * // Full config - customize folder names
+   * modules: {
+   *   dir: 'app/modules',
+   *   pagesDirName: 'views',
+   *   layoutsDirName: 'layouts',
+   * }
+   * ```
+   */
+  modules?: string | ModulesConfig;
+
+  /**
+   * Framework integrations to activate
+   * Simply list the framework names - the integration packages handle the rest
+   * @example ["react", "svelte", "lit"]
+   */
+  integrations?: IntegrationName[];
+
+  /**
+   * MDX processing configuration
+   */
+  mdx?: MDXConfig;
+
+  /**
+   * Image optimization configuration
+   * When enabled, Avalon auto-injects vite-imagetools with sensible defaults.
+   * Set to `false` to disable, or pass an object to customize.
+   * 
+   * @default { enabled: true }
+   * 
+   * @example
+   * ```ts
+   * // Use defaults (webp, quality 80, standard breakpoints)
+   * image: true
+   * 
+   * // Customize
+   * image: {
+   *   defaultFormat: 'avif',
+   *   quality: 90,
+   *   widths: [320, 640, 1024, 1920],
+   * }
+   * 
+   * // Disable
+   * image: false
+   * ```
+   */
+  image?: boolean | ImageConfig;
+
+  /**
+   * Nitro server runtime configuration
+   * When provided, enables Nitro integration for universal deployment
+   * 
+   * @example
+   * ```ts
+   * nitro: {
+   *   preset: 'vercel',
+   *   streaming: true,
+   *   routeRules: {
+   *     '/api/**': { cors: true },
+   *     '/static/**': { cache: { maxAge: 86400 } },
+   *   },
+   * }
+   * ```
+   */
+  nitro?: AvalonNitroConfig;
+
+  /**
+   * Enable verbose logging during development
+   * @default false
+   */
+  verbose?: boolean;
+
+  /**
+   * Auto-discover integrations based on component file extensions
+   * When true, Avalon will automatically activate integrations
+   * based on the components you use, even if not listed in integrations
+   * @default true
+   */
+  autoDiscoverIntegrations?: boolean;
+
+  /**
+   * Validate integrations on startup
+   * When true, Avalon will check that all integrations
+   * implement the required interface correctly
+   * @default true
+   */
+  validateIntegrations?: boolean;
+
+  /**
+   * Show warnings for integration issues
+   * When true, Avalon will log warnings for non-critical
+   * integration problems
+   * @default true
+   */
+  showWarnings?: boolean;
+
+  /**
+   * Enable lazy loading of integration Vite plugins
+   * When true (default), Avalon will only load Vite plugins for integrations
+   * that are actually used in your project, significantly improving cold start time.
+   * 
+   * The lazy loading works by:
+   * 1. Scanning the islands directory to discover which frameworks are used
+   * 2. Only loading Vite plugins for those frameworks at startup
+   * 3. Loading additional plugins on-demand if new frameworks are encountered
+   * 
+   * Set to false to load all configured integrations at startup (slower but predictable).
+   * @default true
+   */
+  lazyIntegrations?: boolean;
+}
+
+/**
+ * Fully resolved MDX configuration with defaults applied
+ */
+export interface ResolvedMDXConfig {
+  jsxImportSource: string;
+  syntaxHighlighting: boolean;
+  remarkPlugins: unknown[];
+  rehypePlugins: unknown[];
+}
+
+/**
+ * Resolved modular architecture configuration
+ */
+export interface ResolvedModulesConfig {
+  dir: string;
+  pagesDirName: string;
+  layoutsDirName: string;
+}
+
+/**
+ * Fully resolved configuration with defaults applied
+ */
+export interface ResolvedAvalonConfig {
+  pagesDir: string;
+  layoutsDir: string;
+  modules: ResolvedModulesConfig | null;
+  integrations: IntegrationName[];
+  mdx: ResolvedMDXConfig;
+  image: ResolvedImageConfig;
+  verbose: boolean;
+  autoDiscoverIntegrations: boolean;
+  validateIntegrations: boolean;
+  showWarnings: boolean;
+  lazyIntegrations: boolean;
+  isDev: boolean;
+}
+
+/**
+ * Re-export Nitro configuration types for convenience
+ */
+export type { AvalonNitroConfig } from "../nitro/config.ts";
+export type {
+  CacheOptions,
+  RouteRule,
+  NitroConfigOutput,
+  AvalonRuntimeConfig,
+  StaticAssetsConfig,
+} from "../nitro/config.ts";